# 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"
    }
  }
  ```

## ACP Protocol Features

### 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.

## 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 🚀*
