Skip to content

SuperagenticAI/zedcode-acps

BranchesTags

Repository files navigation

ZedCode ACPs

⚠️ Work in Progress - This project is actively under development. Features may change and documentation is being updated continuously.

Agent Client Protocol (ACP) servers for Claude Code and OpenAI Codex, enabling seamless integration with Zed editor and other ACP-compatible clients.

npm version License: MIT

Status

This package provides working ACP implementations for both Claude Code and Codex agents:

  • ✅ Claude Code Agent: Fully functional with session management and streaming
  • ⚠️ Codex Agent: Functional but may require additional configuration depending on your Codex setup
  • 📚 Documentation: Comprehensive but being continuously improved
  • 🔧 Wrapper Solutions: Multiple installation options available for different use cases

Features

  • 🤖 Dual Agent Support: Supports both Claude Code and OpenAI Codex
  • 🔄 Streaming Responses: Real-time streaming output from both agents
  • 🛠️ Tool Call Mapping: Automatic mapping of tool calls to ACP protocol
  • 📝 Session Management: Persistent sessions with resume capability
  • ⚙️ Flexible Configuration: Environment-based configuration options
  • 🎯 Zed Integration: Designed specifically for Zed editor integration

Quick Start

Installation

# Install globally for CLI usage
npm install -g zedcode-acps

# Or install locally in your project
npm install zedcode-acps

Prerequisites

For Claude Code Agent

  1. Install Claude Code: Follow Claude Code installation guide
  2. Set up authentication: claude setup-token

For Codex Agent

  1. Install OpenAI Codex: Follow the OpenAI Codex installation guide
  2. Set up authentication as required by Codex
  3. Ensure Codex is accessible in your PATH or set CODEX_PATH environment variable

Basic Usage

Claude Code Server

# Start Claude ACP server
zedcode-acp-claude

# With debug logging
ACP_DEBUG=true zedcode-acp-claude

# With custom permission mode
ACP_PERMISSION_MODE=acceptEdits zedcode-acp-claude

Codex Server

# Start Codex ACP server
zedcode-acp-codex

# With debug logging
ACP_DEBUG=true zedcode-acp-codex

# With custom codex path
CODEX_PATH=/usr/local/bin/codex zedcode-acp-codex

Installation Options

Option 1: Global npm Installation (Recommended)

# Install globally
npm install -g zedcode-acps

# Use in Zed settings.json
{
  "agent_servers": {
    "codex": {
      "command": "npx",
      "args": ["zedcode-acp-codex"]
    }
  }
}

Option 2: System-wide Wrapper (Best for Zed)

For a cleaner Zed configuration without absolute paths:

# From the project directory
git clone https://github.com/SuperagenticAI/zedcode-acps.git
cd zedcode-acps
pnpm install && pnpm build

# Install system-wide wrapper
sudo ./install-wrapper.sh

Then use this simple Zed config:

{
  "agent_servers": {
    "codex": {
      "command": "zedcode-acp-codex",
      "args": []
    }
  }
}

Option 3: Project-specific Installation

# Clone and build
git clone https://github.com/SuperagenticAI/zedcode-acps.git
cd zedcode-acps
pnpm install && pnpm build

# Use project-specific wrapper in Zed
{
  "agent_servers": {
    "codex": {
      "command": "/path/to/zedcode-acps/user-wrapper.js",
      "args": []
    }
  }
}

Zed Editor Configuration

To use these agents with the Zed editor, you need to add an agent_servers configuration to your settings.json file. You can open your settings.json file by navigating to Zed > Settings > Open Settings.

Below is a comprehensive example that shows how to configure both the Claude and Codex agents with various options. You can copy and paste this into your settings.json file and modify it to your needs.

For a complete reference, you can also see the zed-configuration-example.json file.

{
  "agent_servers": {
    "claude-code": {
      "command": "npx",
      "args": ["zedcode-acp-claude"],
      "env": {
        "ACP_DEBUG": "false",
        "ACP_PERMISSION_MODE": "default"
      }
    },
    "claude-code-permissive": {
      "command": "npx",
      "args": ["zedcode-acp-claude"],
      "env": {
        "ACP_PERMISSION_MODE": "acceptEdits",
        "ACP_DEBUG": "false"
      }
    },
    "codex": {
      "command": "npx",
      "args": ["zedcode-acp-codex"],
      "env": {
        "ACP_DEBUG": "false",
        "CODEX_PATH": "codex"
      }
    },
    "claude-code-debug": {
      "command": "npx",
      "args": ["zedcode-acp-claude"],
      "env": {
        "ACP_DEBUG": "true",
        "ACP_PERMISSION_MODE": "acceptEdits"
      }
    },
    "codex-debug": {
      "command": "npx",
      "args": ["zedcode-acp-codex"],
      "env": {
        "ACP_DEBUG": "true"
      }
    }
  }
}

Configuration Options

  • command: The command to execute to start the agent. We recommend using "npx" to run the agents, as it doesn't require global installation.
  • args: A list of arguments to pass to the command. The first argument should be the name of the agent executable ("zedcode-acp-claude" or "zedcode-acp-codex").
  • env: A map of environment variables to set for the agent process.
    • ACP_DEBUG: Set to "true" to enable debug logging, which is useful for troubleshooting.
    • ACP_PERMISSION_MODE: For the Claude agent, this controls how the agent handles file edits. See the Permission Modes section for more details.
    • CODEX_PATH: For the Codex agent, this specifies the path to the codex executable.

Configuration

Environment Variables

Variable Description Default Agents
ACP_DEBUG Enable verbose logging false Both
ACP_PERMISSION_MODE Claude permission mode default Claude
CODEX_PATH Path to codex executable codex Codex

Permission Modes (Claude)

The bridge supports different permission modes for Claude's file operations:

  • default: Asks for permission on file operations (default)
  • acceptEdits: Auto-accepts file edits, still asks for other operations (recommended)
  • bypassPermissions: Bypasses all permission checks (use with caution!)
  • plan: Planning mode with restricted operations

Dynamic Permission Mode Switching

You can also change permission mode during a conversation by including special markers in your prompt:

  • [ACP:PERMISSION:ACCEPT_EDITS] - Switch to acceptEdits mode
  • [ACP:PERMISSION:BYPASS] - Switch to bypassPermissions mode
  • [ACP:PERMISSION:DEFAULT] - Switch back to default mode

Example:

[ACP:PERMISSION:ACCEPT_EDITS]
Please update all the TypeScript files to use the new API

API Reference

Programmatic Usage

import { ClaudeACPAgent, CodexACPAgent, createServer } from 'zedcode-acps'

// Create a Claude server
const claudeServer = createServer('claude')

// Create a Codex server
const codexServer = createServer('codex')

// Or create agents directly
import { AgentSideConnection } from '@zed-industries/agent-client-protocol'

const connection = new AgentSideConnection(
  (client) => new ClaudeACPAgent(client),
  input,
  output
)

Agent Capabilities

Both agents support the following ACP capabilities:

  • Session Management: Create, load, and manage conversation sessions
  • Streaming Responses: Real-time message streaming
  • Tool Calls: Execute and track tool/function calls
  • Cancellation: Graceful request cancellation
  • Error Handling: Robust error reporting and recovery

Architecture

Claude Code Agent

The Claude agent wraps the @anthropic-ai/claude-code SDK and provides:

  • Direct integration with Claude's streaming API
  • Session persistence and resumption
  • Permission mode management
  • Tool call detection and mapping
  • Real-time response streaming

Codex Agent

The Codex agent interfaces with the OpenAI Codex CLI and provides:

  • Process spawning and management with automatic Node.js detection
  • JSON-RPC communication via codex proto subcommand
  • Protocol version compatibility fixes
  • Output parsing and streaming
  • Tool call extraction
  • Cross-platform compatibility
  • Graceful process cleanup

Development

Building from Source

# Clone the repository
git clone https://github.com/SuperagenticAI/zedcode-acps.git
cd zedcode-acps

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Run in development
pnpm run dev:claude  # Claude server
pnpm run dev:codex   # Codex server

Testing

# Type checking
pnpm run typecheck

# Linting
pnpm run lint

# Formatting
pnpm run format

Contributing

Note: This is a work-in-progress project. Contributions are welcome but please expect active development and potential breaking changes.

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature-name
  3. Make your changes following the existing patterns
  4. Test your changes with both agents
  5. Update documentation as needed
  6. Submit a pull request

Development Guidelines

  • Follow existing TypeScript patterns
  • Test with both Claude Code and Codex agents
  • Update README.md for any configuration changes
  • Add appropriate error handling and logging

Authentication

Claude Code Authentication

This bridge uses Claude Code's built-in authentication. You need to authenticate Claude Code first:

# Login with your Anthropic account
claude setup-token

# Or if you're already logged in through the Claude Code CLI, it will use that session

The bridge will automatically use the existing Claude Code authentication from ~/.claude/config.json.

Codex Authentication

Follow OpenAI's authentication setup for Codex as per their documentation.

Troubleshooting

Common Setup Issues

1. "Claude Code process exited" error

Make sure you're authenticated with Claude Code:

claude setup-token

2. Session not persisting

The bridge correctly maintains session context using Claude's native session management. Each ACP session maps to a Claude session that persists throughout the conversation.

3. Tool calls not working

Tool calls are fully supported. Ensure your Zed client is configured to handle tool call updates properly.

4. Command Not Found

Error: Command 'zedcode-acp-claude' not found

Solutions:

  • Ensure global installation: npm install -g zedcode-acps
  • Check PATH: echo $PATH should include npm global bin directory
  • Use full path in Zed config: /usr/local/bin/zedcode-acp-claude

Codex-Specific Issues

1. "spawn ENOTDIR" Error

This occurs when the Codex binary is a Node.js script (common with npm installations):

Solution: The agent automatically detects Node.js scripts and spawns them correctly. If you encounter this error:

  • Verify Codex installation: which codex
  • Check if it's executable: ls -la $(which codex)
  • Try setting explicit path: "CODEX_PATH": "/usr/local/bin/codex"

2. Infinite Loading/Hanging

If Codex sessions hang on initialization:

Check the logs:

# Enable debug logging
ACP_DEBUG=true zedcode-acp-codex

# Check protocol fixer logs (if using wrapper)
tail -f /tmp/protocol-fixer.log

Common causes:

  • Codex authentication issues
  • Protocol version mismatches (handled by protocol-fixer.js)
  • Process communication failures

3. Protocol Version Mismatch

If you see protocol version errors, the package includes automatic fixes:

For system-wide installation (recommended for Zed):

# From the project directory
sudo ./install-wrapper.sh

Then use this Zed config:

{
  "agent_servers": {
    "codex": {
      "command": "zedcode-acp-codex",
      "args": [],
      "env": {}
    }
  }
}

For project-specific usage:

{
  "agent_servers": {
    "codex": {
      "command": "/path/to/zedcode-acps/user-wrapper.js",
      "args": [],
      "env": {}
    }
  }
}

4. Node.js Script Detection

The agent automatically detects if Codex is a Node.js script by checking:

  • File extension (.js)
  • Shebang line (#!/usr/bin/env node)
  • File contents

If detection fails, you can force Node.js execution by setting the path to the actual script:

{
  "env": {
    "CODEX_PATH": "/usr/local/lib/node_modules/@openai/codex/bin/codex.js"
  }
}

Debug Logging

Enable debug logging for detailed troubleshooting:

ACP_DEBUG=true zedcode-acp-claude
ACP_DEBUG=true zedcode-acp-codex

This will output detailed logs to stderr, including:

  • Session management operations
  • Message processing steps
  • Tool call details
  • Protocol communication
  • Error conditions

Technical Details

Wrapper Architecture

The package includes several wrapper scripts to handle compatibility issues:

protocol-fixer.js

  • Purpose: Fixes protocol version mismatches between Zed and ACP library
  • Function: Intercepts JSON-RPC messages and converts string protocol versions to numbers
  • Logging: Creates detailed logs in /tmp/protocol-fixer.log for debugging

user-wrapper.js

  • Purpose: Provides path-independent execution for project-specific installations
  • Function: Automatically finds project directory and launches protocol-fixer
  • Usage: Can be used directly in Zed config without hardcoded paths

install-wrapper.sh

  • Purpose: Creates a system-wide wrapper for clean Zed configuration
  • Function: Installs a global zedcode-acp-codex command that works from any directory
  • Result: Enables simple Zed config without absolute paths

Session Management

The bridge uses a two-step session management approach:

  1. Creates an ACP session ID initially
  2. On first message, obtains and stores the agent's session ID
  3. Uses session resumption for subsequent messages to maintain context

Message Flow

  1. Client → Wrapper: JSON-RPC messages via stdin/stdout
  2. Wrapper → Agent: Protocol fixes applied, forwarded to agent
  3. Agent → CLI: Converted to agent-specific format (Claude SDK/Codex proto)
  4. CLI → Agent: Stream of response messages
  5. Agent → Client: Converted back to ACP protocol format

Features

Implemented

  • ✅ Full ACP protocol implementation
  • ✅ Session persistence with Claude's native session management
  • ✅ Streaming responses
  • ✅ Text content blocks
  • ✅ Claude SDK integration
  • ✅ Tool call support with proper status updates
  • ✅ Session loading capability
  • ✅ Permission management with configurable modes
  • ✅ Rich content display (todo lists, tool usage)
  • ✅ Codex CLI integration

Planned

  • Image/audio content blocks
  • Advanced error handling
  • Session export/import
  • Enhanced Codex streaming

License

MIT License - see LICENSE file for details.

Acknowledgments

Links

About

Collection of the Agent Client Protocol ACP for Zed Editor

Resources

Readme

License

MIT license

Contributing

Contributing
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages