Using Claude Code in Neovim | Installing and Configuring claudecode.nvim

What is claudecode.nvim?

coder/claudecode.nvim is a community plugin that reimplements the Claude Code IDE extension — officially provided by Anthropic only for VS Code and JetBrains — for Neovim.

It implements the same Model Context Protocol (MCP) over WebSocket as the official extension, giving Claude Code CLI the same ability to recognize file context within the editor. Designed with the philosophy of "elevating Neovim itself to an AI IDE," it lets you invoke Claude Code without changing any of your familiar workflows — terminal operations, keybindings, and Vim motions all remain intact.

Because it is a pure Lua implementation, there is no Python bridge or Node.js dependency; it runs entirely on Neovim's native runtime.

Requirements and Prerequisites

Before installing, confirm the following three points.

1. Neovim 0.8.0 or later is installed
2. Claude Code CLI is installed and the claude command is on your PATH
3. folke/snacks.nvim is registered in your plugin manager

If you manage Claude Code CLI with the local installer (claude migrate-installer), the executable path will be ~/.claude/local/claude. In that case, use the terminal_cmd setting described later.

Installing Claude Code CLI via npm is the most reliable approach.

npm install -g @anthropic-ai/claude-code
claude --version  # verify the version

Installing claudecode.nvim (lazy.nvim)

If you are using lazy.nvim, add the following configuration block to your plugin configuration file (source: GitHub README).

{
  "coder/claudecode.nvim",
  dependencies = {
    "folke/snacks.nvim",
  },
  config = true,
  cmd = {
    "ClaudeCode",
    "ClaudeCodeFocus",
    "ClaudeCodeSend",
    "ClaudeCodeAdd",
    "ClaudeCodeDiffAccept",
    "ClaudeCodeDiffDeny",
  },
}

Writing config = true applies the default configuration. If you need customization, override settings via opts = { ... }.

After restarting Neovim, run :ClaudeCode. If a Claude Code terminal window appears in the right pane, the installation is successful.

Basic Configuration Options

To change settings from their defaults, override them in the opts table (source: GitHub).

opts = {
  -- WebSocket port search range
  port_range = { min = 10000, max = 65535 },
  -- Whether to automatically start the Claude server when Neovim launches
  auto_start = true,
  -- Log output level ("info" / "debug" / "warn" / "error")
  log_level = "info",
  -- Specify the executable path for local installations
  terminal_cmd = nil,  -- e.g.: "~/.claude/local/claude"
  -- Whether to move focus to Claude after :ClaudeCodeSend
  focus_after_send = false,
  -- Whether to automatically send cursor position and selection to Claude
  track_selection = true,
  -- Terminal pane settings
  terminal = {
    split_side = "right",         -- "left" is also available
    split_width_percentage = 0.30, -- allocate 30% of screen width to the Claude pane
    provider = "auto",             -- "snacks" / "native" / "external" / "none"
  },
}

With track_selection = true (the default), the range selected in visual mode is automatically reflected in Claude's context. You can ask "explain this code" and it will target the already-selected function or variable directly.

Command Reference

The commands provided by claudecode.nvim are as follows.

:ClaudeCodeAdd also accepts line numbers. Writing ClaudeCodeAdd path/to/file.lua 10 30 passes only lines 10 through 30 as context.

Keymap Configuration

Typing :ClaudeCode every time is cumbersome. Add shortcuts to the keys table (source: Zenn).

{
  "coder/claudecode.nvim",
  dependencies = { "folke/snacks.nvim" },
  config = true,
  keys = {
    -- Open/close the Claude terminal
    { "<leader>ac", "<cmd>ClaudeCode<cr>",      desc = "Toggle Claude Code" },
    -- Move focus to Claude
    { "<leader>af", "<cmd>ClaudeCodeFocus<cr>", desc = "Focus Claude" },
    -- Send selected text to Claude (visual mode)
    { "<leader>as", "<cmd>ClaudeCodeSend<cr>",  desc = "Send to Claude",  mode = "v" },
    -- Accept/reject diff
    { "<leader>ad", "<cmd>ClaudeCodeDiffAccept<cr>", desc = "Accept changes" },
    { "<leader>ax", "<cmd>ClaudeCodeDiffDeny<cr>",   desc = "Reject changes" },
  },
}

Replace <leader> to match your own configuration. The basic workflow is <Space>ac to toggle, then <Space>as after a visual selection to send.

Diff Workflow — Reviewing, Applying, and Rejecting Changes

The biggest appeal of claudecode.nvim is its native Diff view. When Claude proposes code changes, Neovim's built-in Diff feature displays the "current code" and "proposed code" side by side (source: Qiita).

The basic flow is as follows.

1. Open the terminal with :ClaudeCode and enter your change request
2. When Claude generates or modifies code, the Diff view opens automatically
3. The left pane shows the code before changes, the right pane shows the code after
4. After reviewing, apply with :ClaudeCodeDiffAccept or reject with :ClaudeCodeDiffDeny

Approval is done file by file, so changes spanning multiple files can be reviewed one file at a time. The design prevents the mistake of "applying everything at once and noticing a problem later."

With keymaps configured, <leader>ad / <leader>ax handle everything, eliminating the need to switch back from the Diff view to the terminal.

How the WebSocket Connection Works

Understanding the internal mechanism of how Neovim and Claude Code CLI communicate makes it easier to troubleshoot configuration issues (source: Zenn).

When claudecode.nvim starts, it launches a WebSocket server on a random port and writes the connection information to a ~/.claude/ide/[port].lock file. When Claude Code CLI is launched in the terminal, it reads this lock file and establishes the WebSocket connection.

After connecting, the following information is synchronized in real time via the MCP protocol.

• Cursor position — which file and which line is currently being viewed
• Visual selection range — when track_selection = true
• File context — contents of files added with :ClaudeCodeAdd
• Diff operation results — accept/reject feedback

This architecture is identical to that of the official VS Code / JetBrains extensions, meaning that if Anthropic updates the extension protocol in the future, claudecode.nvim is well-positioned to keep up.

Troubleshooting

:ClaudeCode does not open a window

snacks.nvim may not be loading correctly. Run :checkhealth claudecode to check the status of dependencies.

Not working with a local installation using ~/.claude/local/claude

Add terminal_cmd = "~/.claude/local/claude" to opts. By default, the plugin looks for the claude command on PATH, so an explicit path is required for local installations.

The Diff view appears but characters are garbled

Check that Neovim's encoding is set to utf-8. Add set encoding=utf-8 to your init.lua / init.vim.

A port conflict prevents the server from starting

Change port_range to specify a range without conflicts. Narrowing it, such as { min = 20000, max = 40000 }, also reduces the search time.

For those who want to get the most out of Claude Code in a Neovim environment, claudecode.nvim is currently the most complete option available. With its three strengths — Lua-native, minimal external dependencies, and official protocol compatibility — it can be safely integrated into a production development environment.