acpx

When to use this skill

Use this skill when you need to run coding agents through acpx, manage persistent ACP sessions, queue prompts, or consume structured agent output from scripts.

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.

Core capabilities:

• Persistent multi-turn sessions per repo/cwd
• One-shot execution mode (exec)
• Named parallel sessions (-s/--session)
• 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.

acpx [global_options] [prompt_text...]
acpx [global_options] prompt [prompt_options] [prompt_text...]
acpx [global_options] exec [prompt_options] [prompt_text...]
acpx [global_options] cancel [-s <name>]
acpx [global_options] set-mode <mode> [-s <name>]
acpx [global_options] set <key> <value> [-s <name>]
acpx [global_options] status [-s <name>]
acpx [global_options] sessions [list | new [--name <name>] | close [name] | show [name] | history [name] [--limit <count>]]
acpx [global_options] config [show | init]

acpx [global_options] <agent> [prompt_options] [prompt_text...]
acpx [global_options] <agent> prompt [prompt_options] [prompt_text...]
acpx [global_options] <agent> exec [prompt_options] [prompt_text...]
acpx [global_options] <agent> cancel [-s <name>]
acpx [global_options] <agent> set-mode <mode> [-s <name>]
acpx [global_options] <agent> set <key> <value> [-s <name>]
acpx [global_options] <agent> status [-s <name>]
acpx [global_options] <agent> sessions [list | new [--name <name>] | close [name] | show [name] | history [name] [--limit <count>]]

If prompt text is omitted and stdin is piped, acpx reads prompt text from stdin.

Built-in agent registry

Friendly agent names resolve to commands:

• codex -> npx @zed-industries/codex-acp
• claude -> npx @zed-industries/claude-agent-acp
• gemini -> gemini
• opencode -> npx opencode-ai
• pi -> npx pi-acp

Rules: