acpx

When to use this skill

Use this skill when you need to run coding agents through acpx, manage persistent ACP sessions, queue prompts, override the Claude system prompt, prune stale sessions, consume structured agent output from scripts, or compose multi-agent workflows declaratively with acpx/flows.

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)
• Idempotent session creation (sessions ensure)
• Session retention controls (sessions prune with age filters and history cleanup)
• Portable session export/import for moving records and history across machines
• 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) with optional --suppress-reads
• Built-in agent registry plus raw --agent escape hatch
• Claude system prompt override via --system-prompt / --append-system-prompt
• Optional terminal capability disable via --no-terminal for review-only flows
• Tool whitelist (--allowed-tools), turn cap (--max-turns), retry on transient failures (--prompt-retries)
• Multi-agent flows via acpx flow run and the acpx/flows authoring API (defineFlow, decision, decisionEdge, acp, action, compute, checkpoint)

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>] | ensure [--name <name>] | close [name] | show [name] | history [name] [--limit <count>] | export [name] --output <path> | import <archive> [--name <name>] [--cwd <dir>] | prune [--dry-run] [--before <date> | --older-than <days>] [--include-history]]
acpx [global_options] config [show | init]
acpx [global_options] flow run <file> [--input-json '<json>' | --input-file <path>] [--default-agent <name>]

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>] | ensure [--name <name>] | close [name] | show [name] | history [name] [--limit <count>] | export [name] --output <path> | import <archive> [--name <name>] [--cwd <dir>] | prune [--dry-run] [--before <date> | --older-than <days>] [--include-history]]

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:

…