All notable changes to the Claude Code Neovim Integration will be documented in

this file.

The format is based on[Keep a Changelog](https://keepachangelog.com/en/1.0.0/),

and this project adheres to[Semantic Versioning](https://semver.org/spec/v2.0.0.html).

- Initial project structure and core modules

-**Complete WebSocket server implementation using pure Neovim built-ins**

- RFC 6455 compliant WebSocket protocol implementation

- JSON-RPC 2.0 message handling for MCP protocol

- Zero external dependencies (uses vim.loop, vim.json, vim.schedule)

- Support for multiple concurrent client connections

- Ping/pong keepalive and graceful connection management

- Full HTTP upgrade handshake with proper WebSocket accept key generation

- WebSocket frame encoding/decoding with masking support

- Lock file management for Claude CLI discovery

- Selection tracking for editor context

- MCP tool implementations

- Basic commands (:ClaudeCodeStart,:ClaudeCodeStop,:ClaudeCodeStatus,:ClaudeCodeSend)

- Automatic shutdown and cleanup on Neovim exit

- Testing framework with Busted (55 tests passing)

- Development environment with Nix flakes

- Comprehensive luacheck linting with zero warnings

-**Selection Tracking**: Added a configurable delay (`visual_demotion_delay_ms`) before a visual selection is "demoted" after exiting visual mode. This helps preserve visual context when quickly switching to the Claude terminal.

-**At-Mention Feature**: Implemented the`:ClaudeCodeSend` command to send visual selections as`at_mentioned` notifications to Claude, providing focused code context. This includes updates to selection tracking and server broadcasting logic.

- Initial alpha release

First public release of claudecode.nvim - the first Neovim IDE integration for

Claude Code.

- Pure Lua WebSocket server (RFC 6455 compliant) with zero dependencies

- Full MCP (Model Context Protocol) implementation compatible with official extensions

- Interactive terminal integration for Claude Code CLI

- Real-time selection tracking and context sharing

- Native Neovim diff support for code changes

- Visual selection sending with`:ClaudeCodeSend` command

- Automatic server lifecycle management

-`:ClaudeCode` - Toggle Claude terminal

-`:ClaudeCodeSend` - Send visual selection to Claude

-`:ClaudeCodeOpen` - Open/focus Claude terminal

-`:ClaudeCodeClose` - Close Claude terminal

- Neovim >= 0.8.0

- Claude Code CLI

This file providesguidance to Claude Code(claude.ai/code)when working withcode inthisrepository.

This file providescontext for Claude Code when working with thiscodebase.

A Neovim plugin thatintegrates with Claude Code CLI to provide seamless AI coding experience. The plugin creates aWebSocket server using pure Neovim built-ins to communicate with Claude Code CLI via JSON-RPC 2.0, implementing the Model Context Protocol (MCP).

claudecode.nvim -A Neovim plugin thatimplements the sameWebSocket-based MCP protocol as Anthropic's official IDE extensions. Built with pure Lua and zero dependencies.

This document provides an overview oftheproject structure, development workflow, and implementation priorities for contributors.

Quick guide for contributors totheclaudecode.nvim project.

| Component| Status| Priority| Notes|

| ----------------------| -------| --------| -------------------------------------------------------|

| Basic plugin structure| ✅ Done| -| Initial setup complete|

| Configuration system| ✅ Done| -| Support for user configuration|

| WebSocket server| ✅ Done| -| Pure Lua RFC 6455 compliant|

| Lock file management| ✅ Done| -| Basic implementation complete|

| Selection tracking| ✅ Done| -| Enhanced with multi-mode support|

| MCP tools framework| ✅ Done| -| Dynamic tool registration and schema system|

| Core MCP tools| ✅ Done| -| openFile, openDiff, getCurrentSelection, getOpenEditors|

| Diff integration| ✅ Done| -| Native Neovim diff with configurable options|

| Terminal integration| ✅ Done| -| Snacks.nvim and native terminal support|

| Tests| ✅ Done| -|55+ tests passing, comprehensive coverage|

| CI pipeline| ✅ Done| -| GitHub Actions configured|

| Documentation| ✅ Done| -| Complete documentation|

| Component| Status| Priority| Notes|

| ----------------------| -------| --------| --------------------------------------------------------------------|

| Basic plugin structure| ✅ Done| -| Initial setup complete|

| Configuration system| ✅ Done| -| Support for user configuration|

| WebSocket server| ✅ Done| -| Pure Lua RFC 6455 compliant|

| Lock file management| ✅ Done| -| Basic implementation complete|

| Selection tracking| ✅ Done| -| Enhanced with multi-mode support|

| MCP tools framework| ✅ Done| -| Dynamic tool registration and schema system|

| Core MCP tools| ✅ Done| -| openFile, openDiff, getCurrentSelection, getOpenEditors|

| Diff integration| ✅ Done| -| Native Neovim diff with configurable options|

| Terminal integration| ✅ Done| -| Snacks.nvim and native terminal support|

| Tests| ✅ Done| -|Comprehensive test suite with unit, component, and integration tests|

| CI pipeline| ✅ Done| -| GitHub Actions configured|

| Documentation| ✅ Done| -| Complete documentation|

This document explains the protocol and architecture behind Claude Code's IDE integrations, based on reverse-engineering the VS Code extension. Use this guide to build your own integrations or understand how the official ones work.

Claude Code extensions create WebSocket servers in your IDE that Claude connects to. They use a WebSocket variant of MCP (Model Context Protocol) that only Claude supports. The IDE writes a lock file with connection info, sets some environment variables, and Claude automatically connects when launched.

When you launch Claude Code from your IDE, here's what happens:

The extension starts a WebSocket server on a random port (10000-65535) that listens for connections from Claude.

The IDE writes a discovery file to`~/.claude/ide/[port].lock`:

{

"pid":12345,// IDE process ID

"workspaceFolders": ["/path/to/project"],// Open folders

"ideName":"VS Code",// or "Neovim", "IntelliJ", etc.

"transport":"ws"// WebSocket transport

}

When launching Claude, the IDE sets:

-`CLAUDE_CODE_SSE_PORT`: The WebSocket server port

-`ENABLE_IDE_INTEGRATION`: Set to "true"

Claude reads the lock files, finds the matching port from the environment, and connects to the WebSocket server.

Communication uses WebSocket with JSON-RPC 2.0 messages:

{

"jsonrpc":"2.0",

"method":"method_name",

"params": {

},

"id":"unique-id"// for requests that expect responses

}

The protocol is based on MCP (Model Context Protocol) specification 2025-03-26, but uses WebSocket transport instead of stdio/HTTP.

These are notifications the IDE sends to keep Claude informed:

Sent whenever the user's selection changes:

{

"jsonrpc":"2.0",

"method":"selection_changed",

"params": {

"text":"selected text content",

"filePath":"/absolute/path/to/file.js",

"fileUrl":"file:///absolute/path/to/file.js",

"selection": {

"start": {"line":10,"character":5 },

"end": {"line":15,"character":20 },

"isEmpty":false

}

}

}

When the user explicitly sends a selection as context:

{

"jsonrpc":"2.0",

"method":"at_mentioned",

"params": {

"filePath":"/path/to/file",

"lineStart":10,

"lineEnd":20

}

}

According to the MCP spec, Claude should be able to call tools, but**current implementations are mostly one-way** (IDE → Claude).

{

"jsonrpc":"2.0",

"id":"request-123",

"method":"tools/call",

"params": {

"name":"openFile",

"arguments": {

"filePath":"/path/to/file.js"

}

}

}

{

"jsonrpc":"2.0",

"id":"request-123",

"result": {

"content": [{"type":"text","text":"File opened successfully" }]

}

}

The extensions register these tools that Claude can (theoretically) call:

1.**openFile** - Open a file and optionally select text

{

"filePath":"/path/to/file.js",

"startText":"function hello",// Find and select from this text

"endText":"}"// To this text

}

2.**openDiff** - Show a diff and wait for user action (blocking!)

{

"old_file_path":"/path/to/original.js",

"new_file_path":"/path/to/modified.js",

"new_file_contents":"// Modified content...",

"tab_name":"Proposed changes"

}

Returns`FILE_SAVED` or`DIFF_REJECTED` based on user action.

3.**getCurrentSelection** - Get the current text selection

4.**getOpenEditors** - List all open files

5.**getWorkspaceFolders** - Get project folders

6.**getDiagnostics** - Get errors/warnings from the IDE

7.**saveDocument** - Save a file

8.**close_tab** - Close a tab by name (note the inconsistent naming!)

- Most tools follow camelCase naming except`close_tab` (uses snake_case)

- The`openDiff` tool is unique - it's**blocking** and waits for user interaction

- Tools return MCP-formatted responses with content arrays

- There's also`executeCode` for Jupyter notebooks in the VS Code extension

Here's the minimum viable implementation:

localserver=create_websocket_server("127.0.0.1",random_port)

locallock_data= {

pid=vim.fn.getpid(),

workspaceFolders= {vim.fn.getcwd() },

ideName="YourEditor",

}

write_json(lock_path,lock_data)

export CLAUDE_CODE_SSE_PORT=12345

export ENABLE_IDE_INTEGRATION=true

claude# Claude will now connect!

send_message({

jsonrpc="2.0",

method="selection_changed",

params= {... }

})

register_tool("openFile",function(params)

return {content= {{type="text",text="Done"}} }

end)

**Always bind to localhost (`127.0.0.1`) only!** This ensures the WebSocket server is not exposed to the network.

With this protocol knowledge, you can:

- Build integrations for any editor

- Create agents that connect to existing IDE extensions

- Extend the protocol with custom tools

- Build bridges between different AI assistants and IDEs

The WebSocket MCP variant is currently Claude-specific, but the concepts could be adapted for other AI coding assistants.

-[MCP Specification](https://spec.modelcontextprotocol.io)

-[Claude Code Neovim Implementation](https://github.com/coder/claudecode.nvim)

-[Official VS Code Extension](https://github.com/anthropic-labs/vscode-mcp) (minified source)