Supported Platforms

• macOS: Intel (x86_64) and Apple Silicon (aarch64)
• Linux: x86_64
• Windows: Not currently supported

Language Server Activation

The Claude Code extension runs as a Language Server Protocol (LSP) server and automatically activates when you open files with the following extensions:

• Rust (.rs)
• JavaScript (.js)
• TypeScript (.ts, .tsx)
• Python (.py)
• Markdown (.md)

Adding Support for Other File Types

To enable Claude Code integration for additional file types, edit the claude-code-extension/extension.toml file:

[language_servers.claude-code-server]
name = "Claude Code Server"
languages = ["Rust", "JavaScript", "TypeScript", "Python", "Markdown", "Go", "Java"]

[language_servers.claude-code-server.language_ids]
"Rust" = "rust"
"JavaScript" = "javascript"
"TypeScript" = "typescript"
"Python" = "python"
"Markdown" = "markdown"
"Go" = "go"
"Java" = "java"

After modifying the configuration, reinstall extention and restart Zed for the changes to take effect.

Usage

Once the extension is installed, follow these steps to connect Claude Code CLI with Zed:

Connecting Claude Code to Zed

1. Open a supported file in Zed: Create or open a file with one of the supported extensions (.rs, .js, .ts, .tsx, .py, .md)

2. Start Claude Code CLI: Open your terminal and run:

   claude-code
   

3. Enable IDE integration: In Claude Code CLI, run:

   /ide
   

4. Select the integration: Choose claude-code-server from the menu that appears

5. Test the connection:

   • Select some text in your Zed editor
   • In Claude Code CLI, ask: "What did I select?"
   • If connected properly, Claude should be able to see your selected text

What to Expect

Once connected, you'll have:

• Text selection sharing: Selected text in Zed is automatically available to Claude Code CLI
• File context: Claude can see which file you're working in
• Real-time updates: Changes in your selection are immediately reflected in Claude

Verifying the Connection

To confirm everything is working:

• Check for a lock file at ~/.claude/ide/[port].lock
• The Claude Code CLI will display IDE integration status
• Text selections in Zed should be visible to Claude Code CLI

Development Setup

Prerequisites for Development

• Rust toolchain with wasm32-wasi target:

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  rustup target add wasm32-wasi
  

• Zed editor for testing
• Claude Code CLI for integration testing
• Make (usually pre-installed on macOS/Linux)

Quick Development Workflow

The easiest way to develop and test changes:

1. Make your changes to the server code in claude-code-server/src/

2. Build and deploy in one command:

   make dev-build
   

3. Restart Zed to use the updated binary

4. Test your changes (optional guided testing):

   make dev-test
   

Available Development Commands

| Command | Description | |---------|-------------| | make dev-build | Build release version and deploy to Zed | | make dev-debug | Build debug version and deploy to Zed | | make dev-clean | Remove development deployment | | make dev-test | Build, deploy, and show testing instructions | | make status | Show current deployment status | | make help | Show all available commands |

Development Workflow Details

The Makefile automatically:

• Detects your platform (macOS Intel/ARM, Linux)
• Builds the server with the correct target
• Creates the Zed extension directory if needed
• Copies the binary with the platform-specific name
• Provides clear feedback and next steps

Development Mode Configuration

By default, the extension uses production behavior (downloads from GitHub releases). For developers who want to test local changes, you can enable development mode via the FORCE_DEVELOPMENT_MODE flag in claude-code-extension/src/lib.rs:

// Set this to true to always use local development binaries instead of GitHub releases
// DEFAULT: false (production behavior - downloads from GitHub)
const FORCE_DEVELOPMENT_MODE: bool = false;

When FORCE_DEVELOPMENT_MODE = false (DEFAULT):

• ✅ Standard production behavior
• ✅ Downloads official binaries from GitHub releases
• ✅ Only uses development binaries in claude-code-zed project directories
• ✅ Safe for end users and most development work

When FORCE_DEVELOPMENT_MODE = true (DEVELOPMENT):

• Extension always looks for manually copied binaries first
• Works in any directory (not just claude-code-zed projects)
• Allows using local fixes immediately without waiting for releases

To enable development mode:

1. Edit claude-code-extension/src/lib.rs
2. Change FORCE_DEVELOPMENT_MODE to true
3. Restart Zed (the extension will recompile automatically)
4. Use make dev-build to deploy your local binary

Example Development Session

# Check current status
make status

# Make changes to claude-code-server/src/lsp.rs
# Build and deploy
make dev-build

# Restart Zed and test
make dev-test

Manual Installation (Alternative)

If you prefer manual control:

# Build the server
cd claude-code-server
cargo build --release

# Copy to Zed extension directory (macOS ARM example)
cp target/release/claude-code-server \
  "$HOME/Library/Application Support/Zed/extensions/work/claude-code-zed/claude-code-server-macos-aarch64"

Troubleshooting Development Issues

"Binary not found" after make dev-build:

• Ensure Zed was completely restarted
• Check make status to verify deployment
• Try make dev-clean && make dev-build

Extension compilation errors:

• Verify Rust toolchain: rustup target list --installed | grep wasm32-wasi
• Update Rust: rustup update
• Clear Zed cache and reinstall extension

Connection issues:

• Check file type is supported (.rs, .js, .ts, .py, .md)
• Look for "Claude Code Server" in Zed's language server status
• Restart both Zed and Claude Code CLI

Architecture Overview

This project consists of two components:

1. Zed Extension (claude-code-zed)

• Purpose: Zed editor integration and LSP communication
• Technology: Rust compiled to WebAssembly
• Responsibilities:
  • Editor selection tracking
  • File reference handling
  • LSP server lifecycle management
  • Communication with the companion server

2. Claude Code Server (claude-code-server)

• Purpose: WebSocket server for Claude Code CLI communication
• Technology: Native Rust application
• Responsibilities:
  • WebSocket server on localhost
  • Lock file management (~/.claude/ide/[port].lock)
  • Authentication token handling
  • JSON-RPC protocol implementation
  • Bridging between Zed extension and Claude Code CLI

How It Works

The system implements the Claude Code protocol as documented in claudecode.nvim PROTOCOL.md:

Communication Flow

1. Zed Extension Startup:

   • Extension loads in Zed's WASM environment
   • Establishes LSP connection to companion server
   • Begins tracking editor selections and file changes

2. Companion Server Launch:

   • claude-code-server starts as native process
   • Creates WebSocket server on random port (10000-65535)
   • Writes discovery lock file to ~/.claude/ide/[port].lock
   • Sets environment variables (CLAUDE_CODE_SSE_PORT, ENABLE_IDE_INTEGRATION)

3. Claude Code Discovery:

   • Claude Code CLI discovers server via lock file
   • Authenticates using UUID token from lock file
   • Establishes WebSocket connection

4. Bidirectional Communication:

   • Zed → Claude: Selection changes, file