acpx

CRITICAL: Background Execution Required

MUST use run_in_background: true for ALL acpx bash commands. Running acpx in the foreground will block Claude Code and make the session unusable.

When executing any acpx command:

{
  "command": "acpx codex 'your prompt here'",
  "run_in_background": true
}

Failure to run in background will cause Claude Code to block indefinitely while waiting for the agent to complete.

What acpx is

acpx is a headless, scriptable CLI client for the Agent Client Protocol (ACP). It is built for agent-to-agent communication over the command line and avoids PTY scraping.

WARNING: Never use Claude-related ACP agents with acpx. Using Claude to call Claude creates recursive loops and unpredictable behavior. Use alternative agents like codex, openclaw, gemini, etc.

Core capabilities:

• Persistent multi-turn sessions per repo/cwd
• One-shot execution mode (exec)
• Named parallel sessions (-s/--session, prompt verb only)
• Queue-aware prompt submission with optional fire-and-forget (--no-wait)
• Cooperative cancel command (cancel) for in-flight turns
• Graceful cancellation via ACP session/cancel on interrupt
• Session control methods (set-mode, set <key> <value>)
• Agent reconnect/resume after dead subprocess detection
• Prompt input via stdin or --file
• Config files with global+project merge and config show|init
• Session metadata/history inspection (sessions show, sessions history)
• Local agent process checks via status
• Stable ACP client methods for filesystem and terminal requests
• Stable ACP authenticate handshake via env/config credentials
• Structured streaming output (text, json, quiet)
• Built-in agent registry plus raw --agent escape hatch

Install

npm i -g acpx

For normal session reuse, prefer a global install over npx.

Command model

prompt is the default verb. Commands follow this shape:

acpx [global_options] [<agent>] [verb] [prompt_options] [prompt_text...]

Verbs: prompt (default), exec, cancel, set-mode, set, status, sessions, config. When prompt text is omitted and stdin is piped, acpx reads from stdin. For the full grammar, see ./references/cli.md.

Built-in agent registry

IMPORTANT: Do NOT use Claude-related ACP agents (e.g., claude, @zed-industries/claude-agent-acp). These create recursive agent-calling-agent scenarios that can cause infinite loops or unexpected behavior.

Friendly agent names resolve to commands:

• pi -> npx pi-acp
• openclaw -> openclaw acp
• codex -> npx @zed-industries/codex-acp
• gemini -> gemini --acp
• cursor -> cursor-agent acp
• copilot -> copilot --acp --stdio
• droid -> droid exec --output-format acp
• kimi -> kimi acp
• opencode -> npx -y opencode-ai acp
• kiro -> kiro-cli acp
• kilocode -> npx -y @kilocode/cli acp
• qwen -> qwen --acp

Rules:

• Default agent is codex for top-level prompt, exec, and sessions.
• Unknown positional agent tokens are treated as raw agent commands.
• --agent <command> explicitly sets a raw ACP adapter command.
• Do not combine a positional agent and --agent in the same command.

Commands

Prompt (default, persistent session)

acpx codex 'fix flaky tests'             # implicit prompt
acpx codex prompt 'fix flaky tests'      # explicit
acpx prompt 'fix flaky tests'            # defaults to codex

Auto-resumes the saved session for scope (agentCommand, cwd, name?). Exits code 4 if no session exists — run sessions new first. Queue-aware: submits to running queue owner when a prompt is already in flight. On interrupt, sends ACP session/cancel before force-kill.

Prompt options: -s/--session <name>, --no-wait, -f/--file <path>.

Exec (one-shot)

acpx codex exec 'summarize this repo'

Runs a single prompt in a temporary session; does not reuse or persist session state.

Note: -s/--session is a prompt-verb option only — it does not apply to exec. For parallel one-shot patterns across separate working dirs, see the Cross-repo / worktree section below.

Cancel / Mode / Set

acpx codex cancel
acpx codex set-mode auto
acpx codex set approval_policy conservative

cancel sends cooperative session/cancel via IPC. set-mode calls ACP session/set_mode (mode ids are adapter-defined). set calls ACP session/set_config_option. Both route through queue-owner IPC when active.

Sessions

acpx sessions list
acpx sessions new [--name <name>]
acpx sessions close [name]
acpx sessions show [name]
acpx sessions history [name] [--limit <count>]
acpx status

acpx codex sessions new --name backend
acpx codex sessions close backend
acpx codex sessions show backend
acpx codex sessions history backend --limit 20
acpx codex status

Key behaviors: sessions and sessions list are equivalent. new creates a fresh session for the current scope; if an open session already exists in that scope, it is soft-closed. show [name] prints metadata; history [name] prints turn previews (default 20).

For the complete subcommand list including ensure, all flags, global options, config keys, session scoping rules, queueing internals, output format details, permission modes, and exit codes, see ./references/cli.md.

Global options (summary)

• --agent <command>: raw ACP command (escape hatch)
• --cwd <dir>: working directory for session scope
• --approve-all / --approve-reads (default) / --deny-all: permission mode (mutually exclusive)
• --format <fmt>: text (default), json, quiet
• --timeout <seconds> / --ttl <seconds>: timing controls (TTL default 300s)
• --verbose: ACP/debug logs to stderr

Reference summary

Config files: merged in order — ~/.acpx/config.json (global), <cwd>/.acpxrc.json (project). Key settings: defaultAgent, defaultPermissions, ttl, timeout, format, agents map, auth map. Run acpx config show to inspect; acpx config init to create global template.

Session behavior: sessions scoped by agentCommand + absolute cwd + optional name. Records in ~/.acpx/sessions/*.json. Prompt mode auto-resumes by walking up to git root; exits code 4 if no session found (run sessions new). Dead PIDs are respawned. Use -s/--session <name> for parallel conversations.

Prompt queueing: the first acpx process for a session becomes the queue owner; others submit over local IPC. Default: wait for completion. --no-wait: return after enqueue. Ctrl+C sends ACP session/cancel before force-kill. Owner shuts down after TTL idle (default 300s).

Output formats: --format text (default) human-readable stream, --format json NDJSON for automation, --format quiet final text only, --json-strict suppresses non-JSON stderr.

Permission modes: choose one — --approve-all, --approve-reads (default), --deny-all. If all requests are denied/cancelled and none approved, acpx exits with permission-denied status.

For full details on all options, subcommands, exit codes, and IPC internals, see ./references/cli.md.

Practical workflows

Persistent repo assistant (multi-turn):

acpx codex 'inspect failing tests and propose a fix plan'
acpx codex 'apply the smallest safe fix and run tests'

Parallel named sessions + queued follow-up:

acpx codex -s backend 'fix API pagination bug'
acpx codex -s docs 'draft changelog entry for release'
acpx codex --no-wait 'after tests, summarize root causes and next steps'

One-shot and automation:

acpx --format quiet exec 'summarize repo purpose in 3 lines'
acpx --format json codex 'review current branch changes' > events.ndjson
acpx --cwd ~/repos/shop --approve-all codex -s pr-842 \
  'review PR #842 for regressions and propose minimal patch'

Cross-repo / worktree delegation (current repo stays untouched):

# Same shell stays on the orchestration repo; the agent works elsewhere
acpx --cwd /home/dev/code/projectB codex exec 'audit failing CI in projectB'

# Parallel one-shots on isolated worktrees — no --session needed,
# each acpx process is naturally isolated by its --cwd
acpx --cwd /tmp/codex-worktrees/feat-A codex exec 'task A' &
acpx --cwd /tmp/codex-worktrees/feat-B codex exec 'task B' &
wait
# Note: when calling from Claude Code Bash tool, use run_in_background: true
# per-call instead — the &+wait pattern blocks the tool until both complete.

The --cwd overrides the working directory the agent sees, but skills, MCP servers, and config are still loaded from the user's home (~/.codex/ for codex). Add the target paths to [projects."<path>"] in ~/.codex/config.toml (Codex-side TOML config) to avoid trust prompts on first use.

For more examples including stdin/file prompts, session management, and JSON automation pipelines, see ./references/cli.md.