# ACP Protocol Integration

> ACP (Agent Client Protocol) is a universal agent protocol introduced by the Zed editor that decouples the core functionality (server) from the user interface (client) of agents, allowing users to freely combine different agent servers and clients.

CodeBuddy Code natively supports the ACP protocol and can seamlessly integrate as an agent server with ACP-compatible editors.

## Quick Start

### Starting ACP Mode

Use the `--acp` parameter to start the CodeBuddy Code ACP server:

```bash
codebuddy --acp
```

## Zed Editor Integration

### Configuration Steps

Open the Zed configuration file (`~/.config/zed/settings.json`) and add the following configuration:

```json
{
  "agent_servers": {
    "CodeBuddy Code": {
      "command": "codebuddy",
      "args": ["--acp"],
      "env": {}
    }
  }
}
```

You can then create a CodeBuddy Code Thread in the Zed sidebar and start using it.

### Configuration Details

- **command**: Specify the CodeBuddy Code command path (ensure `codebuddy` is available in PATH)
- **args**: Use `["--acp"]` to enable ACP protocol mode
- **env**: Optional environment variable configuration, for example:

  ```json
  {
    "env": {
      "CODEBUDDY_API_KEY": "your-api-key",
      "CODEBUDDY_INTERNET_ENVIRONMENT": "internal"
    }
  }
  ```

  > **Note**: When using `CODEBUDDY_API_KEY`, you must correctly configure `CODEBUDDY_INTERNET_ENVIRONMENT` based on your version:
  > - International version: Do not set (default)
  > - China version: `internal`
  > - iOA version: `ioa`
  >
  > See [Identity and Access Management documentation](iam.md#getting-a-personal-api-key) for details.

## ACP Protocol Features

### Authentication Information Extension

CodeBuddy Code returns user information in the `_meta` field of the `authenticate` response:

```json
{
  "_meta": {
    "codebuddy.ai/userinfo": {
      "userId": "User ID",
      "userName": "Username",
      "userNickname": "User Nickname"
    }
  }
}
```

Clients can use this information to provide a better user experience, such as displaying the currently logged-in user or personalizing the interface.

### Tool Proxy Mechanism

The ACP protocol supports client-side proxying of certain tool operations, improving performance and security:

- **File Operation Proxy**: Based on the client's `fs.readTextFile` and `fs.writeTextFile` capabilities
- **Terminal Operation Proxy**: Based on the client's `terminal` capability

When a client declares support for these capabilities, CodeBuddy Code will automatically proxy related tool calls to the client for execution.

### Command List Push

CodeBuddy Code automatically pushes the available slash command list (`available_commands_update`) to the client when creating a new session, enabling the client to:

- Provide command auto-completion functionality
- Display command hints and help information
- Dynamically update available commands

The command list automatically filters out local commands (such as `/clear`, `/exit`) and client-specific commands (such as `/theme`, `/config`), only pushing commands applicable to ACP mode.

### Agent Teams Protocol Extension

CodeBuddy Code extends the ACP protocol through the `_meta` field of `session_info_update` to support real-time status push for Agent Teams multi-agent collaboration.

#### Team Status Events

The following event types are pushed via `_meta['codebuddy.ai/teamUpdate']`:

**Member Status Change** (`member_status_change`):

```json
{
  "sessionUpdate": "session_info_update",
  "_meta": {
    "codebuddy.ai/teamUpdate": {
      "type": "member_status_change",
      "teamName": "my-team",
      "isAutoTeam": false,
      "members": [
        {
          "name": "ux-designer",
          "color": "blue",
          "description": "UX design analysis",
          "status": "running",
          "taskId": "agent-abc123",
          "sessionId": "session-xyz",
          "tokenUsage": { "inputTokens": 1000, "outputTokens": 500, "lastContextWindow": 42000 },
          "toolCallCount": 5
        }
      ]
    }
  }
}
```

**Team Created** (`team_created`) / **Deleted** (`team_deleted`):

```json
{
  "sessionUpdate": "session_info_update",
  "_meta": {
    "codebuddy.ai/teamUpdate": {
      "type": "team_created",
      "teamName": "my-team"
    }
  }
}
```

#### Member Streaming Messages

Real-time messages from members (text, tool calls) are pushed through standard ACP events, with the `_meta['codebuddy.ai/memberEvent']` tag added to identify the message source:

```json
{
  "sessionUpdate": "agent_message_chunk",
  "content": { "type": "text", "text": "Analyzing architecture proposal..." },
  "_meta": {
    "codebuddy.ai/memberEvent": "tech-architect"
  }
}
```

Upon receiving events with the `memberEvent` tag, clients should route them to the corresponding member's conversation timeline rather than the main conversation area.

#### Page Refresh Recovery

After a page refresh, once `loadSession`'s `replayHistory` is complete, the current Team status is automatically pushed (`member_status_change` event), so clients do not need to make a separate request. When `AcpTeamBridge` subscribes to a member session, it automatically replays the complete history, so member conversation data is also fully restored via ACP SSE without requiring additional HTTP APIs.

## Other Editor Support

ACP is an open protocol, so theoretically any editor supporting ACP can integrate with CodeBuddy Code. Configuration is similar to Zed:

```json
{
  "agent_servers": {
    "CodeBuddy": {
      "command": "codebuddy",
      "args": ["--acp"]
    }
  }
}
```

## Troubleshooting

### Connection Failed

**Problem**: Zed cannot connect to CodeBuddy

**Solution**:

1. Confirm the `codebuddy` command is available:

   ```bash
   which codebuddy
   ```

2. Test ACP mode startup:

   ```bash
   codebuddy --acp
   ```

3. Check if the configuration file JSON format is correct

### Tool Call Failed

**Problem**: File operation or command execution errors

**Solution**:

1. Check working directory permissions
2. View CodeBuddy logs

## Related Links

- [CLI Reference](./cli-reference.md) - View all command-line parameters
- [IDE Integration Guide](./ide-integrations.md) - More editor integration methods
- [ACP Protocol Specification](https://github.com/agentclientprotocol/agent-client-protocol) - Detailed protocol documentation

---

*Through the ACP protocol, integrate CodeBuddy Code into your favorite editor 🚀*
