Configure ACP subagents

As a developer, you can use ACP (Agent Client Protocol) subagents to delegate parts of a Coder Agents task to external coding agents in your workspace. A harness, such as Codex or Claude Code, is a program that runs an external coding agent. An ACP adapter launches the harness and connects it to Coder through the Agent Client Protocol.

PrerequisitesCopy Anchor Link

ACP subagents are experimental. Your deployment administrator must include chat-acp-subagents in the CODER_EXPERIMENTS environment variable or the coder server --experiments list.

You need a running workspace attached to your chat. ACP subagents are available in the main chat in execute mode. They aren't available in plan mode or to Coder Agents subagents.

Configure a harnessCopy Anchor Link

Configure harnesses inside the workspace where you want the subagents to run. This example uses Claude Code, but the steps for other harnesses are similar. Visit the ACP registry to explore other available harnesses.

1. Install the harness and its ACP adapter in your workspace.

   For Claude Code, use the Claude Agent SDK ACP adapter and its installation instructions. The example configuration uses the adapter's claude-agent-acp executable.

2. Authenticate the harness in the workspace using its own authentication instructions.

   ACP subagents use the harness's credentials, independently of the providers configured for Coder Agents. The workspace needs network access to the harness's model provider.

3. Create the ~/.coder/acp directory in the workspace user's home directory.

4. Add a file named claude.json to that directory with the following content:

   Copy Text

   {
     "display_name": "Claude Code",
     "command": "claude-agent-acp"
   }

   The command must start the ACP adapter, which launches the harness. The adapter executable must be available to the workspace agent. Use an absolute executable path if the adapter isn't on the workspace agent's PATH.

Each .json file directly inside ~/.coder/acp/ configures one harness. The filename without .json is the harness identifier (for example, claude). Files in subdirectories aren't loaded.

ACP subagents use the harness's own tools and configuration. They don't inherit the chat's MCP servers. Coder automatically approves tool permission requests received through the adapter.

Check the context popupCopy Anchor Link

You can find the harnesses available to your agent in the context popup. Open the context usage indicator in the chat composer. The ACP section lists available harnesses by identifier, grouped under their configuration directory.

Coder discovers harnesses after workspace startup scripts finish and checks for configuration changes every 30 seconds. The harness list updates automatically in existing chats when Coder detects a change. You don't need to restart the workspace after you edit a harness configuration.

Delegate a taskCopy Anchor Link

In execute mode, send a message that names the harness and the task you want to delegate. For example:

Use the claude ACP subagent to review the authentication changes.

ACP subagent toolsCopy Anchor Link

The main agent can use these tools when an ACP harness is available in the workspace attached to your chat.

acp_spawn_agentCopy Anchor Link

Starts a subagent with a configured harness in your workspace and sends it the delegated task. Adapters usually expose options that the main agent can configure, such as the model or operating mode. The available options depend on the harness and ACP adapter.

acp_wait_agentCopy Anchor Link

Waits for a subagent's current turn to finish and returns its text reply to the main agent. While it waits, the chat streams the subagent's messages and tool activity. A timeout or canceled wait leaves the subagent running.

acp_message_agentCopy Anchor Link

Sends a follow-up message to an idle subagent, starting another turn in the same session. Subagents that are still working reject new messages.

acp_interrupt_agentCopy Anchor Link

Requests cancellation of a subagent's current turn. The main agent uses acp_wait_agent to confirm when the subagent stops.

TroubleshootingCopy Anchor Link

If a harness doesn't load as expected, check the workspace agent logs for errors.