claude-code.nvim

To develop for claude-code.nvim, you must install Neovim (0.10.0+), Git, Make, LuaRocks, stylua (formatter), and luacheck (linter). Optional but recommended tools include ripgrep and fd.

Ubuntu/Debian

# Install Neovim (from PPA for latest version)
sudo add-apt-repository ppa:neovim-ppa/unstable
sudo apt-get update
sudo apt-get install neovim

# Install luarocks and other dependencies
sudo apt-get install luarocks ripgrep fd-find git make

# Install luacheck
sudo luarocks install luacheck

# Install stylua
curl -L -o stylua.zip $(curl -s https://api.github.com/repos/JohnnyMorganz/StyLua/releases/latest | grep -o "https://.*stylua-linux-x86_64.zip")
unzip stylua.zip
chmod +x stylua
sudo mv stylua /usr/local/bin/

Arch Linux

# Install dependencies
sudo pacman -S neovim luarocks ripgrep fd git make

# Install luacheck
sudo luarocks install luacheck

# Install stylua (from AUR)
yay -S stylua

Fedora

# Install dependencies
sudo dnf install neovim luarocks ripgrep fd-find git make

# Install luacheck
sudo luarocks install luacheck

# Install stylua
curl -L -o stylua.zip $(curl -s https://api.github.com/repos/JohnnyMorganz/StyLua/releases/latest | grep -o "https://.*stylua-linux-x86_64.zip")
unzip stylua.zip
chmod +x stylua
sudo mv stylua /usr/local/bin/

macOS

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install neovim luarocks ripgrep fd git make

# Install luacheck
luarocks install luacheck

# Install stylua
brew install stylua

Windows (Scoop)

# Install scoop if not already installed
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression

# Install dependencies
scoop install neovim git make ripgrep fd

# Install luarocks
scoop install luarocks

# Install luacheck
luarocks install luacheck

# Install stylua
scoop install stylua

Windows (Chocolatey)

# Install chocolatey if not already installed
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install dependencies
choco install neovim git make ripgrep fd

# Install luarocks
choco install luarocks

# Install luacheck
luarocks install luacheck

# Install stylua (download from GitHub)
# Visit https://github.com/JohnnyMorganz/StyLua/releases

Commands

• :ClaudeCode: Toggles the Claude Code terminal window.
• :ClaudeCodeContinue: Resumes the most recent conversation (requires --continue variant).
• :ClaudeCodeResume: Displays an interactive conversation picker (requires --resume variant).
• :ClaudeCodeVerbose: Enables verbose logging (requires --verbose variant).

Note: Commands are automatically generated based on your command_variants configuration.

Default Key Mappings

• <leader>ac: Toggle Claude Code terminal window (Normal mode).
• <C-,>: Toggle Claude Code terminal window (Normal and Terminal modes).

Variant Mappings (if configured)

• <leader>cC: Toggle Claude Code with --continue flag.
• <leader>cV: Toggle Claude Code with --verbose flag.

Terminal Navigation & Scrolling

While inside the Claude Code terminal:

• <C-h/j/k/l>: Navigate to the window on the left, below, above, or right.
• <C-f>: Scroll full-page down.
• <C-b>: Scroll full-page up.

Note: After scrolling with <C-f> or <C-b>, press i to re-enter insert mode to continue typing.

Configure the plugin by passing a table to the setup() function.

Key Configuration Sections:

• window: Controls terminal window behavior, including split_ratio, position (e.g., "botright", "float"), and enter_insert.
• window.float: Settings for floating windows, such as width, height, row, col, relative, and border (e.g., "rounded", "double").
• refresh: Manages file change detection via enable, updatetime, and timer_interval.
• git: Use use_git_root to automatically set the working directory to the git root.
• command: The CLI command used to launch Claude Code (defaults to "claude").
• command_variants: Define custom command-line arguments (like --continue or --verbose) which will automatically generate corresponding Neovim commands and keymaps.
• keymaps: Define custom mappings for toggle (normal and terminal modes) and variants.

require("claude-code").setup({
  -- Terminal window settings
  window = {
    split_ratio = 0.3,
    position = "botright",
    enter_insert = true,
    hide_numbers = true,
    hide_signcolumn = true,
    
    -- Floating window configuration (only applies when position = "float")
    float = {
      width = "80%",
      height = "80%",
      row = "center",
      col = "center",
      relative = "editor",
      border = "rounded",
    },
  },
  -- File refresh settings
  refresh = {
    enable = true,
    updatetime = 100,
    timer_interval = 1000,
    show_notifications = true,
  },
  -- Git project settings
  git = {
    use_git_root = true,
  },
  -- Shell-specific settings
  shell = {
    separator = '&&',
    pushd_cmd = 'pushd',
    popd_cmd = 'popd',
  },
  -- Command settings
  command = "claude",
  -- Command variants
  command_variants = {
    continue = "--continue",
    resume = "--resume",
    verbose = "--verbose",
  },
  -- Keymaps
  keymaps = {
    toggle = {
      normal = "<C-,>",
      terminal = "<C-,>",
      variants = {
        continue = "<leader>cC",
        verbose = "<leader>cV",
      },
    },
    window_navigation = true,
    scrolling = true,
  }
})