Skip to content

Commit f09d900

Browse files
committed
docs: reorganize and streamline project documentation
Consolidate documentation into clear, focused files: - Restructure ARCHITECTURE.md for technical implementation details - Streamline CHANGELOG.md with consistent formatting - Update CLAUDE.md with comprehensive development commands - Enhance DEVELOPMENT.md with contributor guidelines - Add PROTOCOL.md documenting WebSocket/MCP implementation - Create STORY.md explaining project motivation and goals - Remove redundant docs files and findings.md This reorganization improves documentation clarity and makes the project more accessible to contributors. Change-Id: Id1a0979680025c6aed44aca42e2462c87bc43458 Signed-off-by: Thomas Kosiewski <[email protected]>
1 parent f9a8ab7 commit f09d900

File tree

10 files changed

+663
-1704
lines changed

10 files changed

+663
-1704
lines changed

ARCHITECTURE.md

Lines changed: 187 additions & 267 deletions
Large diffs are not rendered by default.

CHANGELOG.md

Lines changed: 28 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,30 @@
11
# Changelog
22

3-
All notable changes to the Claude Code Neovim Integration will be documented in
4-
this file.
5-
6-
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
7-
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
8-
9-
## [Unreleased]
10-
11-
### Added
12-
13-
- Initial project structure and core modules
14-
- **Complete WebSocket server implementation using pure Neovim built-ins**
15-
- RFC 6455 compliant WebSocket protocol implementation
16-
- JSON-RPC 2.0 message handling for MCP protocol
17-
- Zero external dependencies (uses vim.loop, vim.json, vim.schedule)
18-
- Support for multiple concurrent client connections
19-
- Ping/pong keepalive and graceful connection management
20-
- Full HTTP upgrade handshake with proper WebSocket accept key generation
21-
- WebSocket frame encoding/decoding with masking support
22-
- Lock file management for Claude CLI discovery
23-
- Selection tracking for editor context
24-
- MCP tool implementations
25-
- Basic commands (:ClaudeCodeStart, :ClaudeCodeStop, :ClaudeCodeStatus, :ClaudeCodeSend)
26-
- Automatic shutdown and cleanup on Neovim exit
27-
- Testing framework with Busted (55 tests passing)
28-
- Development environment with Nix flakes
29-
- Comprehensive luacheck linting with zero warnings
30-
- **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.
31-
- **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.
32-
33-
### Changed
34-
35-
## [0.1.0-alpha] - TBD
36-
37-
- Initial alpha release
3+
## [0.1.0] - 2025-06-02
4+
5+
### Initial Release
6+
7+
First public release of claudecode.nvim - the first Neovim IDE integration for
8+
Claude Code.
9+
10+
#### Features
11+
12+
- Pure Lua WebSocket server (RFC 6455 compliant) with zero dependencies
13+
- Full MCP (Model Context Protocol) implementation compatible with official extensions
14+
- Interactive terminal integration for Claude Code CLI
15+
- Real-time selection tracking and context sharing
16+
- Native Neovim diff support for code changes
17+
- Visual selection sending with `:ClaudeCodeSend` command
18+
- Automatic server lifecycle management
19+
20+
#### Commands
21+
22+
- `:ClaudeCode` - Toggle Claude terminal
23+
- `:ClaudeCodeSend` - Send visual selection to Claude
24+
- `:ClaudeCodeOpen` - Open/focus Claude terminal
25+
- `:ClaudeCodeClose` - Close Claude terminal
26+
27+
#### Requirements
28+
29+
- Neovim >= 0.8.0
30+
- Claude Code CLI

CLAUDE.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
# CLAUDE.md
22

3-
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
3+
This file provides context for Claude Code when working with this codebase.
44

55
## Project Overview
66

7-
A Neovim plugin that integrates with Claude Code CLI to provide seamless AI coding experience. The plugin creates a WebSocket server using pure Neovim built-ins to communicate with Claude Code CLI via JSON-RPC 2.0, implementing the Model Context Protocol (MCP).
7+
claudecode.nvim - A Neovim plugin that implements the same WebSocket-based MCP protocol as Anthropic's official IDE extensions. Built with pure Lua and zero dependencies.
88

99
## Common Development Commands
1010

DEVELOPMENT.md

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# Claude Code Neovim Integration: Development Guide
1+
# Development Guide
22

3-
This document provides an overview of the project structure, development workflow, and implementation priorities for contributors.
3+
Quick guide for contributors to the claudecode.nvim project.
44

55
## Project Structure
66

@@ -29,20 +29,20 @@ claudecode.nvim/
2929

3030
## Core Components Implementation Status
3131

32-
| Component | Status | Priority | Notes |
33-
| ---------------------- | ------- | -------- | ------------------------------------------------------- |
34-
| Basic plugin structure | ✅ Done | - | Initial setup complete |
35-
| Configuration system | ✅ Done | - | Support for user configuration |
36-
| WebSocket server | ✅ Done | - | Pure Lua RFC 6455 compliant |
37-
| Lock file management | ✅ Done | - | Basic implementation complete |
38-
| Selection tracking | ✅ Done | - | Enhanced with multi-mode support |
39-
| MCP tools framework | ✅ Done | - | Dynamic tool registration and schema system |
40-
| Core MCP tools | ✅ Done | - | openFile, openDiff, getCurrentSelection, getOpenEditors |
41-
| Diff integration | ✅ Done | - | Native Neovim diff with configurable options |
42-
| Terminal integration | ✅ Done | - | Snacks.nvim and native terminal support |
43-
| Tests | ✅ Done | - | 55+ tests passing, comprehensive coverage |
44-
| CI pipeline | ✅ Done | - | GitHub Actions configured |
45-
| Documentation | ✅ Done | - | Complete documentation |
32+
| Component | Status | Priority | Notes |
33+
| ---------------------- | ------- | -------- | -------------------------------------------------------------------- |
34+
| Basic plugin structure | ✅ Done | - | Initial setup complete |
35+
| Configuration system | ✅ Done | - | Support for user configuration |
36+
| WebSocket server | ✅ Done | - | Pure Lua RFC 6455 compliant |
37+
| Lock file management | ✅ Done | - | Basic implementation complete |
38+
| Selection tracking | ✅ Done | - | Enhanced with multi-mode support |
39+
| MCP tools framework | ✅ Done | - | Dynamic tool registration and schema system |
40+
| Core MCP tools | ✅ Done | - | openFile, openDiff, getCurrentSelection, getOpenEditors |
41+
| Diff integration | ✅ Done | - | Native Neovim diff with configurable options |
42+
| Terminal integration | ✅ Done | - | Snacks.nvim and native terminal support |
43+
| Tests | ✅ Done | - | Comprehensive test suite with unit, component, and integration tests |
44+
| CI pipeline | ✅ Done | - | GitHub Actions configured |
45+
| Documentation | ✅ Done | - | Complete documentation |
4646

4747
## Development Priorities
4848

PROTOCOL.md

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
# How Claude Code IDE Extensions Actually Work
2+
3+
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.
4+
5+
## TL;DR
6+
7+
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.
8+
9+
## How Discovery Works
10+
11+
When you launch Claude Code from your IDE, here's what happens:
12+
13+
### 1. IDE Creates a WebSocket Server
14+
15+
The extension starts a WebSocket server on a random port (10000-65535) that listens for connections from Claude.
16+
17+
### 2. Lock File Creation
18+
19+
The IDE writes a discovery file to `~/.claude/ide/[port].lock`:
20+
21+
```json
22+
{
23+
"pid": 12345, // IDE process ID
24+
"workspaceFolders": ["/path/to/project"], // Open folders
25+
"ideName": "VS Code", // or "Neovim", "IntelliJ", etc.
26+
"transport": "ws" // WebSocket transport
27+
}
28+
```
29+
30+
### 3. Environment Variables
31+
32+
When launching Claude, the IDE sets:
33+
34+
- `CLAUDE_CODE_SSE_PORT`: The WebSocket server port
35+
- `ENABLE_IDE_INTEGRATION`: Set to "true"
36+
37+
### 4. Claude Connects
38+
39+
Claude reads the lock files, finds the matching port from the environment, and connects to the WebSocket server.
40+
41+
## The Protocol
42+
43+
Communication uses WebSocket with JSON-RPC 2.0 messages:
44+
45+
```json
46+
{
47+
"jsonrpc": "2.0",
48+
"method": "method_name",
49+
"params": {
50+
/* parameters */
51+
},
52+
"id": "unique-id" // for requests that expect responses
53+
}
54+
```
55+
56+
The protocol is based on MCP (Model Context Protocol) specification 2025-03-26, but uses WebSocket transport instead of stdio/HTTP.
57+
58+
## Key Message Types
59+
60+
### From IDE to Claude
61+
62+
These are notifications the IDE sends to keep Claude informed:
63+
64+
#### 1. Selection Updates
65+
66+
Sent whenever the user's selection changes:
67+
68+
```json
69+
{
70+
"jsonrpc": "2.0",
71+
"method": "selection_changed",
72+
"params": {
73+
"text": "selected text content",
74+
"filePath": "/absolute/path/to/file.js",
75+
"fileUrl": "file:///absolute/path/to/file.js",
76+
"selection": {
77+
"start": { "line": 10, "character": 5 },
78+
"end": { "line": 15, "character": 20 },
79+
"isEmpty": false
80+
}
81+
}
82+
}
83+
```
84+
85+
#### 2. At-Mentions
86+
87+
When the user explicitly sends a selection as context:
88+
89+
```json
90+
{
91+
"jsonrpc": "2.0",
92+
"method": "at_mentioned",
93+
"params": {
94+
"filePath": "/path/to/file",
95+
"lineStart": 10,
96+
"lineEnd": 20
97+
}
98+
}
99+
```
100+
101+
### From Claude to IDE
102+
103+
According to the MCP spec, Claude should be able to call tools, but **current implementations are mostly one-way** (IDE → Claude).
104+
105+
#### Tool Calls (Future)
106+
107+
```json
108+
{
109+
"jsonrpc": "2.0",
110+
"id": "request-123",
111+
"method": "tools/call",
112+
"params": {
113+
"name": "openFile",
114+
"arguments": {
115+
"filePath": "/path/to/file.js"
116+
}
117+
}
118+
}
119+
```
120+
121+
#### Tool Responses
122+
123+
```json
124+
{
125+
"jsonrpc": "2.0",
126+
"id": "request-123",
127+
"result": {
128+
"content": [{ "type": "text", "text": "File opened successfully" }]
129+
}
130+
}
131+
```
132+
133+
## Available MCP Tools
134+
135+
The extensions register these tools that Claude can (theoretically) call:
136+
137+
### Core Tools
138+
139+
1. **openFile** - Open a file and optionally select text
140+
141+
```json
142+
{
143+
"filePath": "/path/to/file.js",
144+
"startText": "function hello", // Find and select from this text
145+
"endText": "}" // To this text
146+
}
147+
```
148+
149+
2. **openDiff** - Show a diff and wait for user action (blocking!)
150+
151+
```json
152+
{
153+
"old_file_path": "/path/to/original.js",
154+
"new_file_path": "/path/to/modified.js",
155+
"new_file_contents": "// Modified content...",
156+
"tab_name": "Proposed changes"
157+
}
158+
```
159+
160+
Returns `FILE_SAVED` or `DIFF_REJECTED` based on user action.
161+
162+
3. **getCurrentSelection** - Get the current text selection
163+
4. **getOpenEditors** - List all open files
164+
5. **getWorkspaceFolders** - Get project folders
165+
6. **getDiagnostics** - Get errors/warnings from the IDE
166+
7. **saveDocument** - Save a file
167+
8. **close_tab** - Close a tab by name (note the inconsistent naming!)
168+
169+
### Implementation Notes
170+
171+
- Most tools follow camelCase naming except `close_tab` (uses snake_case)
172+
- The `openDiff` tool is unique - it's **blocking** and waits for user interaction
173+
- Tools return MCP-formatted responses with content arrays
174+
- There's also `executeCode` for Jupyter notebooks in the VS Code extension
175+
176+
## Building Your Own Integration
177+
178+
Here's the minimum viable implementation:
179+
180+
### 1. Create a WebSocket Server
181+
182+
```lua
183+
-- Listen on localhost only (important!)
184+
local server = create_websocket_server("127.0.0.1", random_port)
185+
```
186+
187+
### 2. Write the Lock File
188+
189+
```lua
190+
-- ~/.claude/ide/[port].lock
191+
local lock_data = {
192+
pid = vim.fn.getpid(),
193+
workspaceFolders = { vim.fn.getcwd() },
194+
ideName = "YourEditor",
195+
transport = "ws"
196+
}
197+
write_json(lock_path, lock_data)
198+
```
199+
200+
### 3. Set Environment Variables
201+
202+
```bash
203+
export CLAUDE_CODE_SSE_PORT=12345
204+
export ENABLE_IDE_INTEGRATION=true
205+
claude # Claude will now connect!
206+
```
207+
208+
### 4. Handle Messages
209+
210+
```lua
211+
-- Send selection updates
212+
send_message({
213+
jsonrpc = "2.0",
214+
method = "selection_changed",
215+
params = { ... }
216+
})
217+
218+
-- Implement tools (if needed)
219+
register_tool("openFile", function(params)
220+
-- Open file logic
221+
return { content = {{ type = "text", text = "Done" }} }
222+
end)
223+
```
224+
225+
## Security Considerations
226+
227+
**Always bind to localhost (`127.0.0.1`) only!** This ensures the WebSocket server is not exposed to the network.
228+
229+
## What's Next?
230+
231+
With this protocol knowledge, you can:
232+
233+
- Build integrations for any editor
234+
- Create agents that connect to existing IDE extensions
235+
- Extend the protocol with custom tools
236+
- Build bridges between different AI assistants and IDEs
237+
238+
The WebSocket MCP variant is currently Claude-specific, but the concepts could be adapted for other AI coding assistants.
239+
240+
## Resources
241+
242+
- [MCP Specification](https://spec.modelcontextprotocol.io)
243+
- [Claude Code Neovim Implementation](https://github.com/coder/claudecode.nvim)
244+
- [Official VS Code Extension](https://github.com/anthropic-labs/vscode-mcp) (minified source)

0 commit comments

Comments
 (0)