Skip to content

Latest commit

 

History

History
127 lines (98 loc) · 12.3 KB

agents.md

File metadata and controls

127 lines (98 loc) · 12.3 KB
title Agents
description Built-in agent registry — every friendly name acpx ships with, the ACP adapter it spawns, the upstream coding agent it wraps, and per-agent notes.

acpx ships with a registry of friendly agent names. Each one resolves to a specific ACP adapter command. On Unix, unknown names fall through as raw commands, and --agent <command> supports custom launchers. On Windows, configure a named agent with structured argv instead (see Custom agents).

The default agent for top-level commands like acpx exec … and acpx prompt … is codex.

Built-in registry

These 30 launch profiles identify supported ACP entry points. Follow each agent guide for installation, authentication, and capability limits. Ante is experimental and cannot reopen sessions after disconnect.

Agent Profile Adapter command
Pi Pi pi npx --package=pi-acp -- pi-acp
OpenClaw OpenClaw openclaw openclaw acp
Codex Codex codex npx -y --package=@agentclientprotocol/codex-acp -- codex-acp
Claude Code Claude Code claude npx -y --package=@agentclientprotocol/claude-agent-acp -- claude-agent-acp
Gemini CLI Gemini CLI gemini gemini --acp
Cursor Cursor cursor cursor-agent acp
GitHub Copilot GitHub Copilot copilot copilot --acp --stdio
Ante Ante ante ante acp (experimental)
Antigravity Antigravity antigravity agy_acp_server.par (platform arguments)
DeepSeek Harness DeepSeek Harness deepseek-harness dsh --profile acp
Devin Devin devin devin acp
Factory Droid Factory Droid droid droid exec --output-format acp
fast-agent fast-agent fast-agent uvx fast-agent-mcp acp
fx fx fx fx acp
Grok Build Grok Build grok-build grok agent stdio
Goose Goose goose goose acp
iFlow iFlow iflow iflow --experimental-acp
Junie Junie junie junie --acp=true
Kilocode Kilocode kilocode npx -y --package=@kilocode/cli -- kilo acp
Kimi Kimi kimi kimi acp
Kiro Kiro kiro kiro-cli-chat acp
MCode MCode mcode mcode acp
Mux Mux mux npx -y --package=mux -- mux acp via an ACPX-owned npm range
Octomind Octomind octomind octomind acp developer:general
OpenCode OpenCode opencode npx -y --package=opencode-ai -- opencode acp
Poolside Poolside pool pool acp
Qoder Qoder qoder qodercli --acp
Qwen Code Qwen Code qwen qwen --acp
Trae Trae trae traecli acp serve
ZeroClaw ZeroClaw zeroclaw zeroclaw acp

factory-droid and factorydroid also resolve to the built-in droid adapter.

Common shape

Built-in profiles share this command surface. Available operations depend on the capabilities advertised by the adapter:

acpx <agent> [prompt_text...]                 # implicit prompt
acpx <agent> prompt [prompt_text...]          # explicit prompt
acpx <agent> exec [prompt_text...]            # one-shot, no saved session
acpx <agent> cancel [-s <name>]               # cooperative session/cancel
acpx <agent> set-mode <mode> [-s <name>]      # session/set_mode
acpx <agent> set <key> <value> [-s <name>]    # session/set_config_option
acpx <agent> status [-s <name>]
acpx <agent> sessions [list | new | ensure | close | show | history | prune]

See Prompting, Sessions, and Session control for the cross-agent semantics.

Per-agent notes

Notes that override or extend the cross-agent behavior live below.

Pi

  • Built-in name: pi
  • Default command: npx --package=pi-acp -- pi-acp
  • Upstream: mariozechner/pi

OpenClaw

For source builds, see the OpenClaw checkout override.

Codex

  • Built-in name: codex
  • Default command: npx -y --package=@agentclientprotocol/codex-acp -- codex-acp
  • Upstream: agentclientprotocol/codex-acp
  • Runtime controls exposed by current codex-acp releases: ACP modes and session config options, including the advertised model selector.
  • acpx --model <id> codex … and acpx codex set model <id> apply the requested model through the advertised ACP config option. Legacy adapters that advertise models use session/set_model.

Claude

  • Built-in name: claude
  • Default command: npx -y --package=@agentclientprotocol/claude-agent-acp -- claude-agent-acp
  • Upstream: agentclientprotocol/claude-agent-acp
  • The built-in package range is pinned by acpx so fresh installs pick up Claude model and ACP adapter fixes without depending on a globally installed adapter binary.
  • On Windows, acpx resolves the claude.exe executable from PATH before spawning so launches do not depend on shell-specific command lookup.
  • --system-prompt and --append-system-prompt forward through ACP _meta.systemPrompt on session/new, letting you replace or append to the Claude Code system prompt without leaving a persistent session. The value persists in session_options.system_prompt so ensure/reuse keeps the override. Other agents ignore the field.

Other built-in agents

Setup, authentication, launch overrides, and capability notes live in the agent guides.

Overriding a built-in

Any built-in can be replaced wholesale through config, including args for adapter sub-commands:

{
  "agents": {
    "codex": {
      "command": "/usr/local/bin/codex-acp",
      "args": ["--profile", "ci"]
    }
  }
}

CLI flags still win over config. See Config for precedence rules.

See also

  • Custom agents — --agent <command> and unknown positional names.
  • Sessions — how the agent command becomes part of the session scope key.
  • Authentication — ACPX_AUTH_* env vars and config auth entries for ACP authenticate handshakes.