> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Delegate Coding Tasks to CLI Tools via ACP

> Have your Octop agent hand off coding tasks to external AI CLI tools through the Agent Client Protocol (ACP).

Octop can delegate coding subtasks to external AI coding CLIs — OpenCode, Claude Code, CodeBuddy, Codex, Kimi Code, Cursor CLI, Pi, or your own custom tool — through the built-in `acp_runner` tool. You install the CLI on the machine running Octop, enable it on the **ACP** page, turn on the `acp_runner` tool for your agent, and then ask your agent in chat to use it. Communication uses stdio JSON-RPC; there is no HTTP ACP endpoint.

## Setup

**1. Install the CLI tool**

Install the CLI for the runner(s) you want on the **same machine** where `octop run` executes. For example:

```bash theme={null}
# OpenCode
npm install -g opencode

# Claude Code (via npx — no install needed)
npx -y @zed-industries/claude-agent-acp

# Codex (via npx — no install needed)
npx -y @zed-industries/codex-acp

# Pi ACP adapter (via npx — no install needed)
npx -y pi-acp
```

Install [Kimi Code](https://github.com/MoonshotAI/kimi-code) to provide the `kimi` command. Install Cursor CLI to provide the `agent` command.

**2. Configure a model in the CLI**

Each CLI tool runs on its **own** model and credentials, independent of Octop. Set up the model and authentication inside the CLI itself before enabling it — for example run `opencode auth login` and pick a model, or complete `claude` / `codex` login. If the CLI has no working model configured, the runner will start but return no useful output.

**3. Open the ACP page**

In the sidebar, open **ACP**. This page is visible to administrators.

**4. Enable the runners you want**

Toggle on the runner cards you need. Runner configuration is shared across every agent on the account.

![ACP runners](https://mintcdn.com/octop/P_aBdthWeK4YndCE/images/ui-acp.png?fit=max\&auto=format\&n=P_aBdthWeK4YndCE\&q=85\&s=f31f43da7480cd4c9dba4538d2b0367d)

**5. Enable the acp\_runner tool for your agent**

Select your agent in the top bar, then turn on **Enable ACP Runner tool** at the bottom of the same page. Unlike runner configuration, this toggle applies per agent.

**6. Delegate in chat**

In chat, ask your agent to use `acp_runner` — for example, *"Use acp\_runner with opencode to find the README and summarise it."* Your agent handles the session lifecycle and surfaces any permission prompts inline.

## Built-in runners

| Runner ID | Command | Args |
| - | - | - |
| `opencode` | `opencode` | `acp` |
| `codebuddy` | `codebuddy` | `--acp` |
| `claude_code` | `npx` | `-y`, `@zed-industries/claude-agent-acp` |
| `codex` | `npx` | `-y`, `@zed-industries/codex-acp` |
| `kimi_code` | `kimi` | `acp` |
| `cursor_cli` | `agent` | `acp` |
| `pi` | `npx` | `-y`, `pi-acp` |

Built-in runners cannot be deleted. Add custom runners from the **Add runner** button on the ACP page.

## `acp_runner` tool workflow

When your agent uses `acp_runner`, it drives the external tool through these actions:

| Action | Description |
| - | - |
| `action=list` | List enabled runners and current session state |
| `action=start` | Open a new session: specify `runner` + `message` (and optional `cwd`) |
| `action=message` | Continue an open session with a follow-up message |
| `action=respond` | Answer a `[permission_required]` prompt with the exact option id |
| `action=status` | Check whether the session is open or waiting for a permission response |
| `action=close` | End the session |

Permission prompts from the external tool appear inline in chat. You can pick an option yourself or instruct the agent to call `action=respond` with the option id.

> [!TIP]
>
> If the runner executable is not on `PATH` in the environment where `octop run` starts (common with system services), set an absolute path in the runner's **command** field — for example `/usr/local/bin/opencode` instead of just `opencode`.

## Troubleshooting

> [accordion] Runner start fails with 'Unknown runner'
>
> The ACP service cache is process-wide. After adding a new custom runner, restart `octop run` so the change takes effect.

> [accordion] External runner returns no text
>
> The CLI tool likely has no working model configured, or has an authentication or quota issue. Configure a model inside the CLI and check its own auth status — for example, run `codebuddy auth status` or verify your API key for the relevant service.

> [accordion] Kimi Code, Cursor CLI, or Pi fails to start
>
> Run the built-in command on the Octop host first. Kimi Code requires `kimi` and its login flow. Cursor CLI requires `agent login` or `CURSOR_API_KEY`. Pi requires Node.js and network access the first time `npx -y pi-acp` downloads the adapter.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.