Zed Claude Code

Overview

Zed Claude Code is a multi-protocol server that enables seamless integration between Claude Code and Zed through the Agent Client Protocol (ACP) and Model Context Protocol (MCP). It functions as an intelligent translation layer that bridges different protocol formats while providing robust, scalable communication between Claude Code capabilities and diverse client applications.

Usage

Quick Start

Run the agent directly using NPX or BUNX (no repository cloning required):

# Using NPX
npx zed-claude-code

# Using BUNX  
bunx zed-claude-code

Zed Integration

Configure the agent in your Zed settings by adding it to agent_servers. Open your Zed settings and add:

{
  "agent_servers": {
    "Zed Claude Code": {
      "command": "npx",
      "args": ["zed-claude-code"],
      "env": {}
    }
  }
}

For development or if you prefer bunx:

{
  "agent_servers": {
    "Zed Claude Code": {
      "command": "bunx",
      "args": ["zed-claude-code"],
      "env": {}
    }
  }
}

💡 Note: The server will automatically install @anthropic-ai/claude-code on first run if not present.

For more information on configuring external agents in Zed, see the Zed External Agents documentation.

Architecture

┌─────────────────┐    ACP     ┌─────────────────┐    Claude SDK    ┌─────────────────┐
│                 │◄──────────►│                 │◄────────────────►│                 │
│      Zed        │  stdin/out │ Zed Claude Code │    HTTP/MCP      │   Claude API    │
│                 │            │                 │                  │                 │
└─────────────────┘            └─────────────────┘                  └─────────────────┘
                                        │
                                        │ MCP Tools
                                        ▼
                               ┌─────────────────┐
                               │                 │
                               │  File System    │
                               │  Operations     │
                               │                 │
                               └─────────────────┘

Protocol Flow

Session Creation

Zed initiates ACP connection via stdin/stdout
Zed Claude Code receives initialize and newSession requests
Server creates Claude Code SDK query with MCP server configuration
Internal HTTP server starts for MCP tool communication
Session is stored in Map for O(1) access performance

Tool Execution

Claude requests tool use via SDK
Zed Claude Code translates tool request to ACP format
Zed receives tool call notification with metadata
User approves/denies tool execution in Zed
Tool result flows back through MCP → SDK → ACP chain
Results include location information and diff data

Conversation Management

Session maintains conversation history across messages
Query object per session enables interruption and streaming
Context preserved for follow-up messages
Proper handling of assistant and user message flows

Key Features

🔄 Protocol Translation

ACP ↔ Claude SDK: Message format conversion
Snake_case ↔ CamelCase: External API compatibility with internal code quality
Tool Metadata: Rich UI information for tool calls
URL-based URI Parsing: Robust handling of file:// and zed:// protocols with Unicode support

🛠️ Tool Integration

File Operations: Read, write, edit with diff visualization
Multi-Edit: Batch file modifications with line tracking
Permission System: User approval workflow for tool execution
Caching: Optimized file content caching for performance

🏗️ Architecture Benefits

Map-based Storage: O(1) session lookup performance
Modular Design: Separation of concerns across components
Type Safety: Full TypeScript implementation with strict checking
Error Handling: Comprehensive error propagation and logging
Session Query Management: Per-session query objects with interrupt capability
Test Coverage: 523 comprehensive unit tests ensuring reliability

Development

💡 Repository cloning is only required for development. For usage, see the Usage section above.

Prerequisites

Node.js 18+
Claude Code installed and authenticated
TypeScript development environment

Setup

# Clone repository
git clone https://github.com/suxxes/zed-claude-code.git
cd zed-claude-code

# Install dependencies
npm install

# Build the project
npm run build

# Run in development
npm run dev

# Run tests
npm test

# Linting and formatting
npm run lint
npm run format

Code Standards

TypeScript: Full type coverage required
Biome: Code formatting and linting with npm run lint and npm run format
Testing: Unit tests for new functionality
Comments: Document complex logic and external APIs

Protocol Compatibility

External APIs: Must maintain snake_case for ACP/MCP compatibility
Internal Code: Use camelCase for TypeScript best practices
Tool Names: Follow mcp__zcc__* naming convention
Error Handling: Provide clear error messages for debugging

Tool Reference

File Operations

mcp__zcc__read_file - Read file contents with optional range
mcp__zcc__edit_file - Edit files with old/new text replacement
mcp__zcc__write_file - Write full file contents
mcp__zcc__multi_edit - Batch edit operations

Search Operations

Glob - Pattern-based file matching
Grep - Content search with regex support
LS - Directory listing

Execution Operations

Bash - Command execution with output capture
Task - Agent delegation for complex operations

Planning Operations

TodoWrite - Task management and planning
ExitPlanMode - Plan completion workflow

Web Operations

WebFetch - HTTP content retrieval
WebSearch - Search engine integration

Notebook Operations

NotebookEdit - Jupyter notebook cell editing

Permission System

permission_request - User approval workflow
Supports "Always Allow", "Allow Once", "Reject" options
Tool-specific permission caching

UI Integration

Rich diff visualization with old/new content
Location information with file paths and line numbers
Tool metadata including descriptions and parameters
Plan integration with TodoWrite tool support

Security Considerations

File Access

All file operations respect client capabilities
Path validation prevents directory traversal
Error messages avoid information disclosure

Authentication

Leverages Claude CLI authentication
Supports both CLI login and API key methods
Session isolation prevents cross-session data leaks

Input Validation

Zod schema validation for all tool parameters
Type-safe parameter handling throughout codebase
Comprehensive error handling and logging

Troubleshooting

Common Issues

Authentication Errors

Error: Please run /login

Solution: Run claude /login in terminal or configure API key

Session Not Found

Error: Session not found: uuid

Solution: Check session lifecycle and cleanup logic

Tool Permission Denied

Error: User refused permission to run tool

Solution: User needs to approve tool execution in Zed

Port Conflicts

Error: EADDRINUSE :::port

Solution: Server automatically selects available ports

Debugging

Enable debug logging:

npx zed-claude-code --debug
bunx zed-claude-code --debug

View detailed logs:

tail -f logs/zed-claude-code.log

You can also access ACP logs in Zed using the "dev: open acp logs" command in the Command Palette.

Contributing

Development Setup

Fork the repository
Create feature branch: git checkout -b feature/amazing-feature
Make changes with tests
Ensure build passes: npm run build
Run linting: npm run lint and npm run format
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open Pull Request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Note: This implementation is based on the original Google Gemini Agent Client Protocol implementation and therefore uses the Apache 2.0 license to maintain compatibility with the original open-source project.

Support

For issues and questions:

GitHub Issues: Create an issue
Logs: Enable debug logging for troubleshooting

Built with ❤️ for seamless Zed and Claude Code integration

zed-claude-code