claudecode.nvim

To build a custom integration for Claude Code, you must implement a WebSocket server that follows a specific handshake and discovery protocol. The integration involves four main steps: creating a WebSocket server, writing a lock file for discovery, setting environment variables, and handling JSON-RPC messages.

-- 1. Create a WebSocket Server (Bind to localhost only!)
local server = create_websocket_server("127.0.0.1", random_port)

-- 2. Write the Lock File (~/.claude/ide/[port].lock)
-- Generate a 128-bit token (32-char lowercase hex) using a CSPRNG
local bytes = vim.loop.random(16)
local auth_token = bytes:gsub(".", function(c)
  return string.format("%02x", string.byte(c))
end)

local lock_data = {
  pid = vim.fn.getpid(),
  workspaceFolders = { vim.fn.getcwd() },
  ideName = "YourEditor",
  transport = "ws",
  authToken = auth_token
}
write_json(lock_path, lock_data)

-- 3. Set Environment Variables
-- export CLAUDE_CODE_SSE_PORT=[port]
-- export ENABLE_IDE_INTEGRATION=true

-- 4. Handle Messages (Validate auth on handshake)
function validate_auth(headers)
  local auth_header = headers["x-claude-code-ide-authorization"]
  return auth_header == auth_token
end

-- Example: Send selection updates
send_message({
  jsonrpc = "2.0",
  method = "selection_changed",
  params = { ... }
})

-- Example: Implement tools
register_tool("openFile", function(params)
  return { content = {{ type = "text", text = "Done" }} }
end)

If you set diff_opts.auto_resize_terminal = false, you can manually control the terminal width by hooking into the following User autocmds:

• ClaudeCodeDiffOpened: Fired when a proposed-edit diff opens.
  • event.data fields: tab_name, file_path, new_file_path, is_new_file, diff_window, target_window, terminal_window, tab_number.
• ClaudeCodeDiffClosed: Fired when the diff is accepted, rejected, or closed.
  • event.data fields: tab_name, file_path, reason (e.g., "diff accepted").

Example: Manually setting terminal width to 20% of columns on diff open:

vim.api.nvim_create_autocmd("User", {
  pattern = "ClaudeCodeDiffOpened",
  callback = function(ev)
    local term = ev.data.terminal_window
    if term and vim.api.nvim_win_is_valid(term) then
      vim.api.nvim_win_set_width(term, math.floor(vim.o.columns * 0.20))
    end
  end,
})

vim.api.nvim_create_autocmd("User", {
  pattern = "ClaudeCodeDiffClosed",
  callback = function(ev)
    -- restore your preferred idle layout here
  end,
})

Install claudecode.nvim with folke/snacks.nvim as a dependency. The following configuration uses lazy-loading via cmd and keys to ensure the plugin only loads when needed. Including the cmd list ensures that :ClaudeCode commands are available even before any keymaps are pressed.

{
  "coder/claudecode.nvim",
  dependencies = { "folke/snacks.nvim" },
  config = true,
  -- `cmd` lets lazy.nvim create command stubs that load the plugin on first use,
  cmd = {
    "ClaudeCode",
    "ClaudeCodeFocus",
    "ClaudeCodeSelectModel",
    "ClaudeCodeAdd",
    "ClaudeCodeSend",
    "ClaudeCodeTreeAdd",
    "ClaudeCodeStatus",
    "ClaudeCodeStart",
    "ClaudeCodeStop",
    "ClaudeCodeOpen",
    "ClaudeCodeClose",
    "ClaudeCodeDiffAccept",
    "ClaudeCodeDiffDeny",
    "ClaudeCodeCloseAllDiffs",
  },
  keys = {
    { "<leader>a", nil, desc = "AI/Claude Code" },
    { "<leader>ac", "<cmd>ClaudeCode<cr>", desc = "Toggle Claude" },
    { "<leader>af", "<cmd>ClaudeCodeFocus<cr>", desc = "Focus Claude" },
    { "<leader>ar", "<cmd>ClaudeCode --resume<cr>", desc = "Resume Claude" },
    { "<leader>aC", "<cmd>ClaudeCode --continue<cr>", desc = "Continue Claude" },
    { "<leader>am", "<cmd>ClaudeCodeSelectModel<cr>", desc = "Select Claude model" },
    { "<leader>ab", "<cmd>ClaudeCodeAdd %<cr>", desc = "Add current buffer" },
    { "<leader>as", "<cmd>ClaudeCodeSend<cr>", mode = "v", desc = "Send to Claude" },
    {
      "<leader>as",
      "<cmd>ClaudeCodeTreeAdd<cr>",
      desc = "Add file",
      ft = { "NvimTree", "neo-tree", "oil", "minifiles", "netrw", "snacks_picker_list" },
    },
    -- Diff management
    { "<leader>aa", "<cmd>ClaudeCodeDiffAccept<cr>", desc = "Accept diff" },
    { "<leader>ad", "<cmd>ClaudeCodeDiffDeny<cr>", desc = "Deny diff" },
  },
}

When adding support for new integrations (like file explorers or terminals), you must provide a fixture configuration in fixtures/[integration-name]/.

A valid fixture must include:

• A complete Neovim configuration.
• Plugin dependencies and setup.
• A dev-claudecode.lua file containing development keybindings.

To test using these fixtures, source the helper aliases and use the vv command:

1. source fixtures/nvim-aliases.sh
2. vv <integration-name> (e.g., vv nvim-tree, vv oil, vv mini-files, or vv netrw)

Other helper commands:

• list-configs: Lists available configurations.
• repro: Creates a minimal reproduction environment by copying fixtures/repro/example to /tmp.

# Source fixture aliases
source fixtures/nvim-aliases.sh

# Test with specific integration
vv nvim-tree  # Start Neovim with nvim-tree configuration
vv oil        # Start Neovim with oil.nvim configuration
vv mini-files # Start Neovim with mini.files configuration
vv netrw      # Start Neovim with built-in netrw configuration

# List available configurations
list-configs

# Minimal repro environment
repro