ckVim Setup Guide

A comprehensive development environment setup with Neovim, Zsh, and essential tools.

Quick Start

1. Clone this project into ~/.vim

git clone https://github.com/ckangnz/ckVim.git ~/.vim
cd ~/.vim

2. Run interactive setup

make all

This will show an interactive menu where you can select which components to install:

• brew - Homebrew package manager
• vim - Vim/Neovim configuration
• zsh - Zsh shell with plugins, terminal tools including Herdr, and AGENTS.md symlinks
• fonts - FiraCode Nerd Font
• others - Additional tools (optional, macOS)
• gitignore - Add ck_* to global gitignore + set core.excludesfile

Defaults adapt to your machine: if Homebrew is already installed, vim, zsh, fonts, and gitignore are pre-selected; otherwise only brew is.

Use 1-6 to toggle selections, a to select/deselect all, Enter to confirm, q to quit.

Note: You can press Ctrl+C at any time to stop the installation.

---

Manual Installation

You can also install components individually:

Install Homebrew only

make brew

Install Vim/Neovim

Warning

This will override your existing .vimrc file

Includes: Neovim, Vim, Python3, Node, FZF, Ripgrep, and more

make vim

Install Zsh configuration

Warning

This will override your existing .zshrc file

Includes: Zsh, Herdr, Zap plugin manager, Powerlevel10k theme, and essential CLI tools. Herdr's user configuration is symlinked from this repository; Herdr session state and logs remain local to ~/.config/herdr.

make zsh

After installation, restart your terminal and configure Powerlevel10k:

p10k configure

Install additional tools (These are for macOS)

Includes: Docker, Arc Browser, Kitty terminal, Rectangle, and more (macOS only)

make others

Create symlinks only

make symlink        # All symlinks
make vim_symlink    # Vim/Neovim symlinks only
make zsh_symlink    # Zsh/Herdr/Kitty symlinks only

Reset environment

Remove all managed symlinks. This removes the Herdr config-file link but preserves Herdr runtime state:

make reset

---

Prerequisites

For Linux (WSL/Ubuntu)

Install essential build tools:

# Debian/Ubuntu
sudo apt-get update && sudo apt-get install build-essential

# Arch Linux (SteamOS)
sudo steamos-readonly disable
sudo pacman-key --init
sudo pacman-key --populate archlinux
sudo pacman -Syu
sudo pacman -S --noconfirm base-devel glibc linux-api-headers
sudo steamos-readonly enable

For WSL

Enable Hyper-V on Windows:

1. Open "Turn Windows features on or off"
2. Find Hyper-V and enable it
3. Restart your computer

Install Nerd Font:

• Download FiraCode Nerd Font
• Configure your terminal to use the font

---

Project Structure

~/.vim/
├── Makefile              # Main installation orchestrator
├── scripts/              # Installation scripts
│   ├── interactive_menu.sh    # Interactive target selection
│   ├── install_methods.sh     # Shared installation functions
│   ├── install_vim.sh         # Vim/Neovim setup
│   ├── install_zsh.sh         # Zsh setup
│   ├── install_others.sh      # Additional tools entrypoint
│   └── install_others_menu.sh # Interactive additional-tools picker
├── .vimrc                # Vim configuration
├── .zshrc                # Zsh entrypoint (PATH, plugins, sources below)
├── aliases.zsh           # Shell aliases (sourced by .zshrc)
├── functions.zsh         # Shell functions (sourced by .zshrc)
├── plugins.zsh           # Zap plugin list
├── completions.zsh       # Completion setup (gh, terraform, dotnet, make)
├── AGENTS.md             # AI-agent conventions (symlinked to Claude/Codex)
├── settings/             # App configs (Rectangle, IdeaVim)
├── WSL_Settings/         # Windows Terminal settings
├── .config/
│   ├── nvim/             # Neovim configuration (init.lua + lua/core, lua/plugins)
│   ├── herdr/            # Herdr user configuration
│   ├── kitty/            # Kitty terminal configuration
│   └── lazygit/          # LazyGit configuration
└── notes/                # Documentation and notes

---

Features

Vim/Neovim

• Modern Neovim configuration with LSP support
• Vim fallback configuration
• Custom keybindings and plugins
• File explorer and fuzzy finder

Zsh

• Zap plugin manager
• Powerlevel10k theme
• Syntax highlighting and autosuggestions
• Git integration
• Custom aliases and functions

Additional Tools

• kitty - GPU-accelerated terminal
• lazygit - Terminal UI for git
• lazydocker - Terminal UI for docker
• fzf - Fuzzy finder
• ripgrep - Fast grep alternative
• bat - Cat alternative with syntax highlighting
• lsd - Modern ls alternative

---

Troubleshooting

• zsh compinit: insecure directories

  compaudit | xargs chmod g-w

• Node.js issues

  npm install -g neovim

• Python issues

  $(which python3) -m pip install pynvim

• Update C# language server

  dotnet tool update -g csharp-ls

• FNM Error 13 permission denied

  sudo chown -R $(whoami) /run/user/1000/

• GitHub Projects v2 permission error

  gh auth refresh -s read:project

• WSL clipboard issues

  choco install win32yank

• Linux clipboard issues

  # Ubuntu
  sudo apt install xsel xclip -y
  
  # Arch Linux
  sudo pacman -S xsel

• Linux (Ubuntu) Programs

  • CopyQ (Clipboard Manager) : sudo apt install copyq
  • Window management
    • Install Extension Manager and add Tiling Assistant sudo apt install gnome-shell-extension-manager
    • Enable window size with Super + right click: gsettings set org.gnome.desktop.wm.preferences resize-with-right-button true
  • Korean sudo apt install ibus-hangul and set it in Settings > Keyboard
  • GPU Driver: sudo ubuntu-drivers autoinstall
  • Font issue with brew:

    mkdir -p ~/.local/share/fonts
    ln -sfn $(brew --prefix)/share/fonts ~/.local/share/fonts/brewfonts
    fc-cache -fv

  • Key repeat interval

    gsettings set org.gnome.desktop.peripherals.keyboard delay 200
    gsettings set org.gnome.desktop.peripherals.keyboard repeat-interval 20

• WSL Docker completions error

  # Remove symlink
  sudo rm -rf /usr/share/zsh/vendor-completions/_docker
  # Copy WSL completions
  sudo cp /mnt/wsl/docker-desktop/cli-tools/usr/share/zsh/vendor-completions/_docker /usr/share/zsh/vendor-completions/
  # Make it read-only
  sudo chattr +i /usr/share/zsh/vendor-completions/_docker

---

Available Make Targets

Run make help to see all available targets:

make help

Main targets:

• make all - Interactive installation menu
• make vim - Install Vim/Neovim
• make zsh - Install Zsh configuration (+ agent hooks + AGENTS.md symlinks)
• make others - Install additional tools
• make brew - Install Homebrew
• make fonts - Install FiraCode Nerd Font
• make agents - Symlink AGENTS.md into Claude Code (~/.claude/CLAUDE.md) and Codex (~/.codex/AGENTS.md)
• make gitignore - Add ck_* to global gitignore + set core.excludesfile
• make symlink - Create all symlinks
• make reset - Remove all symlinks
• make help - Show help message

---

Contributing

Feel free to submit issues and pull requests!

License

MIT License - feel free to use and modify as needed.