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

Launch Claude: Run :ClaudeCode to open Claude in a split terminal
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
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:

Creates a WebSocket server on a random port
Writes a lock file to ~/.claude/ide/[port].lock (or $CLAUDE_CONFIG_DIR/ide/[port].lock if CLAUDE_CONFIG_DIR is set) with connection info
Sets environment variables that tell Claude where to connect
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,
      tmux_pane_size = "30%", -- Size for tmux pane (when using tmux provider)
      tmux_split_direction = "h", -- "h" for horizontal, "v" for vertical (when using tmux provider)
    },

    -- 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/ (or $CLAUDE_CONFIG_DIR/ide/ if CLAUDE_CONFIG_DIR is set)
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!)

License

devsunb/claudecode.nvim

ErrorLooks like something went wrong!

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Error
Looks like something went wrong!

Packages