claudecode.nvim

⚠️ Important: IDE integrations are currently broken in Claude Code releases newer than v1.0.27. Please use Claude Code v1.0.27 or older until these issues are resolved:

• Claude Code not detecting IDE integrations #2299
• IDE integration broken after update #2295

The first Neovim IDE integration for Claude Code — bringing Anthropic's AI coding assistant to your favorite editor with a pure Lua implementation.

🎯 TL;DR: When Anthropic released Claude Code with VS Code and JetBrains support, I reverse-engineered their extension and built this Neovim plugin. This plugin implements the same WebSocket-based MCP protocol, giving Neovim users the same AI-powered coding experience.

claudecode-nvim.mp4

What Makes This Special

When Anthropic released Claude Code, they only supported VS Code and JetBrains. As a Neovim user, I wanted the same experience — so I reverse-engineered their extension and built this.

• 🚀 Pure Lua, Zero Dependencies — Built entirely with vim.loop and Neovim built-ins
• 🔌 100% Protocol Compatible — Same WebSocket MCP implementation as official extensions
• 🎓 Fully Documented Protocol — Learn how to build your own integrations (see PROTOCOL.md)
• ⚡ First to Market — Beat Anthropic to releasing Neovim support
• 🛠️ Built with AI — Used Claude to reverse-engineer Claude's own protocol

Installation

{
  "coder/claudecode.nvim",
  dependencies = { "folke/snacks.nvim" },
  config = true,
  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>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" },
    },
    -- Diff management
    { "<leader>aa", "<cmd>ClaudeCodeDiffAccept<cr>", desc = "Accept diff" },
    { "<leader>ad", "<cmd>ClaudeCodeDiffDeny<cr>", desc = "Deny diff" },
  },
}

That's it! The plugin will auto-configure everything else.

Requirements

• Neovim >= 0.8.0
• Claude Code CLI installed
• folke/snacks.nvim for enhanced terminal support

Quick Demo

" Launch Claude Code in a split
:ClaudeCode

" Claude now sees your current file and selections in real-time!

" Send visual selection as context
:'<,'>ClaudeCodeSend

" Claude can open files, show diffs, and more

Usage

1. Launch Claude: Run :ClaudeCode to open Claude in a split terminal
2. Send context:
   • Select text in visual mode and use <leader>as to send it to Claude
   • In nvim-tree/neo-tree/oil.nvim, press <leader>as on a file to add it to Claude's context
3. Let Claude work: Claude can now:
   • See your current file and selections in real-time
   • Open files in your editor
   • Show diffs with proposed changes
   • Access diagnostics and workspace info

Key Commands

• :ClaudeCode - Toggle the Claude Code terminal window
• :ClaudeCodeFocus - Smart focus/toggle Claude terminal
• :ClaudeCodeSend - Send current visual selection to Claude
• :ClaudeCodeAdd <file-path> [start-line] [end-line] - Add specific file to Claude context with optional line range
• :ClaudeCodeDiffAccept - Accept diff changes
• :ClaudeCodeDiffDeny - Reject diff changes

Working with Diffs

When Claude proposes changes, the plugin opens a native Neovim diff view:

• Accept: :w (save) or <leader>aa
• Reject: :q or <leader>ad

You can edit Claude's suggestions before accepting them.

How It Works

This plugin creates a WebSocket server that Claude Code CLI connects to, implementing the same protocol as the official VS Code extension. When you launch Claude, it automatically detects Neovim and gains full access to your editor.

The protocol uses a WebSocket-based variant of MCP (Model Context Protocol) that:

1. Creates a WebSocket server on a random port
2. Writes a lock file to ~/.claude/ide/[port].lock with connection info
3. Sets environment variables that tell Claude where to connect
4. Implements MCP tools that Claude can call

📖 Read the full reverse-engineering story → 🔧 Complete protocol documentation →

Architecture

Built with pure Lua and zero external dependencies:

• WebSocket Server - RFC 6455 compliant implementation using vim.loop
• MCP Protocol - Full JSON-RPC 2.0 message handling
• Lock File System - Enables Claude CLI discovery
• Selection Tracking - Real-time context updates
• Native Diff Support - Seamless file comparison

For deep technical details, see ARCHITECTURE.md.

Advanced Configuration

Complete configuration options

{
  "coder/claudecode.nvim",
  dependencies = { "folke/snacks.nvim" },
  opts = {
    -- Server Configuration
    port_range = { min = 10000, max = 65535 },
    auto_start = true,
    log_level = "info", -- "trace", "debug", "info", "warn", "error"
    terminal_cmd = nil, -- Custom terminal command (default: "claude")

    -- Selection Tracking
    track_selection = true,
    visual_demotion_delay_ms = 50,

    -- Terminal Configuration
    terminal = {
      split_side = "right", -- "left" or "right"
      split_width_percentage = 0.30,
      provider = "auto", -- "auto", "snacks", or "native"
      auto_close = true,
    },

    -- Diff Integration
    diff_opts = {
      auto_close_on_accept = true,
      vertical_split = true,
      open_in_current_tab = true,
    },
  },
  keys = {
    -- Your keymaps here
  },
}

Troubleshooting

• Claude not connecting? Check :ClaudeCodeStatus and verify lock file exists in ~/.claude/ide/
• Need debug logs? Set log_level = "debug" in opts
• Terminal issues? Try provider = "native" if using snacks.nvim

Contributing

See DEVELOPMENT.md for build instructions and development guidelines. Tests can be run with make test.

License

MIT

Acknowledgements

• Claude Code CLI by Anthropic
• Inspired by analyzing the official VS Code extension
• Built with assistance from AI (how meta!)