Skip to content

agents.md

Latest commit

 

History

History
131 lines (102 loc) · 9.39 KB

agents.md

File metadata and controls

131 lines (102 loc) · 9.39 KB
Raw
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

Agent Adapter command Wraps
pi npx pi-acp Pi Coding Agent
openclaw openclaw acp OpenClaw ACP bridge
codex npx -y @agentclientprotocol/codex-acp Codex CLI
claude npx -y @agentclientprotocol/claude-agent-acp Claude Code
gemini gemini --acp Gemini CLI
cursor cursor-agent acp Cursor CLI
copilot copilot --acp --stdio GitHub Copilot CLI
antigravity agy_acp_server.par (platform arguments) Google Antigravity ACP
devin devin acp Devin CLI
droid droid exec --output-format acp Factory Droid
fast-agent uvx fast-agent-mcp acp fast-agent
fx fx acp fx
grok-build grok agent stdio Grok Build
iflow iflow --experimental-acp iFlow CLI
junie junie --acp=true JetBrains Junie
kilocode npx -y @kilocode/cli acp Kilocode
kimi kimi acp Kimi CLI
kiro kiro-cli-chat acp Kiro CLI
mcode mcode acp MiniMax Code
mux mux acp via an ACPX-owned npm range Mux
opencode npx -y opencode-ai acp OpenCode
pool pool acp Poolside
qoder qodercli --acp Qoder CLI
qwen qwen --acp Qwen Code
trae traecli acp serve Trae CLI
zeroclaw zeroclaw acp ZeroClaw

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

Common shape

Every built-in agent supports the same command surface:

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

OpenClaw

For repo-local OpenClaw checkouts, override the built-in command in ~/.acpx/config.json so acpx openclaw … spawns the ACP bridge directly without the pnpm wrapper:

{
  "agents": {
    "openclaw": {
      "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node scripts/run-node.mjs acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"
    }
  }
}

Codex

  • Built-in name: codex
  • Default command: npx -y @agentclientprotocol/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 @agentclientprotocol/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.