acpx

name acpx description Use acpx as a headless ACP CLI for agent-to-agent communication, including prompt/exec/sessions workflows, session scoping, queueing, permissions, output formats, system-prompt overrides, and multi-agent flows authored with defineFlow/decision/decisionEdge. 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 Prompt-response _meta preservation across direct, queued, compare, and embedded-runtime results Built-in agent registry plus raw --agent escape hatch Claude system prompt override via --system-prompt / --append-system-prompt Optional ACP filesystem and terminal capability opt-outs via --no-fs and --no-terminal 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] compare <agent>... '<prompt_text>' acpx [global_options] compare <agent>... --file <path> 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: pi -> npx pi-acp openclaw -> openclaw acp codex -> npx -y @agentclientprotocol/codex-acp (ACPX-owned package range) claude -> npx -y @agentclientprotocol/claude-agent-acp (ACPX-owned package range) gemini -> gemini --acp cursor -> cursor-agent acp copilot -> copilot --acp --stdio droid -> droid exec --output-format acp ( factory-droid and factorydroid also resolve to droid ) fast-agent -> uvx fast-agent-mcp acp grok-build -> grok agent stdio iflow -> iflow --experimental-acp kilocode -> npx -y @kilocode/cli acp kimi -> kimi acp kiro -> kiro-cli-chat acp mcode -> mcode acp (install/authenticate MCode first; prefer exec for one-shot work, and require advertised ACP reload support for cross-invocation continuity) mux -> mux acp via an ACPX-owned npm range opencode -> npx -y opencode-ai acp pool -> pool acp qoder -> qodercli --acp Forwards Qoder-native --allowed-tools and --max-turns startup flags from acpx session options. qwen -> qwen --acp trae -> traecli acp serve zeroclaw -> zeroclaw 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) Implicit: acpx codex 'fix flaky tests' Explicit: acpx codex prompt 'fix flaky tests' acpx prompt 'fix flaky tests' # defaults to codex Behavior: Uses a saved session for the session scope key Auto-resumes prior session when one exists for that scope If no session exists for the scope, exits with NO_SESSION and prompts for sessions new Is queue-aware when another prompt is already running for the same session On interrupt during an active turn, sends ACP session/cancel before force-kill fallback Prompt options: -s, --session <name> : use a named session within the same cwd --no-wait : enqueue and return immediately when session is already busy -f, --file <path> : read prompt text from file ( - means stdin) Exec (one-shot) acpx exec 'summarize this repo' acpx codex exec 'summarize this repo' acpx --model gpt-5.6-sol codex exec --config-option reasoning_effort=xhigh 'review this repo' Behavior: Runs a single prompt in a temporary ACP session Applies --model , then repeatable --config-option <key=value> selections, before prompting Fails before the prompt if the adapter rejects a requested config option Does not reuse or save persistent session state Compare (multi-agent one-shot) acpx compare pi openclaw codex 'summarize this checkout' acpx --format json compare codex claude --file prompt.md Behavior: Runs the same temporary-session prompt against each listed agent Runs agents serially in the requested workspace Reuses the global exec controls: cwd, timeout, permissions, --policy , auth, terminal, retries, model/system options, and output format --format text prints one summary table row per agent --format json or --json prints CompareRow[] --format quiet prints <agent>\t<status> per row Does not create saved sessions or separate compare transcript directories Cancel / Mode / Config / Model acpx codex cancel acpx codex set-mode auto acpx codex set model gpt-5.6-sol acpx codex set reasoning_effort max Behavior: cancel : sends cooperative session/cancel through queue-owner IPC. set-mode : calls ACP session/set_mode . set-mode mode ids are adapter-defined; unsupported values are rejected by the adapter (often Invalid params ). set : calls ACP session/set_config_option . Current codex-acp releases expose model and reasoning_effort as separate config options. --model <id> : Claude-compatible adapters may consume session creation metadata; other agents must advertise a model config option or legacy models metadata. set model <id> : uses session/set_config_option for advertised model config options and preserves session/set_model for explicitly advertised legacy models. Model switches can change or remove reasoning-effort controls. ACPX reconciles saved non-mode selections with the accepted response; select a supported effort again if needed. After reconnect, ACPX restores the saved model when advertised and replays saved config selections before prompting. A replay failure is reported instead of silently using defaults. set-mode / set route through queue-owner IPC when active, otherwise reconnect directly. Sessions acpx sessions acpx sessions list acpx sessions list --filter-cwd . acpx sessions list --cursor <cursor> acpx sessions list -- local acpx sessions new acpx sessions new --name backend acpx sessions ensure acpx sessions ensure --name backend acpx sessions close acpx sessions close backend acpx sessions show acpx sessions history -- limit 20 acpx sessions export backend --output backend-session.json acpx sessions import backend-session.json --name backend-restored acpx sessions prune --dry-run --older-than 7 acpx sessions prune --older-than 30 --include-history acpx status acpx codex sessions acpx codex sessions new --name backend acpx codex sessions ensure --name backend acpx codex sessions close backend acpx codex sessions show backend acpx codex sessions history backend -- limit 20 acpx codex sessions export backend --output backend-session.json acpx codex sessions import backend-session.json --name backend-restored acpx codex sessions prune --before 2026-04-01 --include-history acpx codex status Behavior: sessions and sessions list are equivalent sessions list uses ACP session/list when the agent advertises it; JSON includes agent SessionInfo , _meta , and nextCursor sessions list --filter-cwd <dir> applies the ACP cwd filter, and --cursor <cursor> requests a specific page sessions list --local reads saved acpx records instead new creates a fresh session for the current (agentCommand, cwd, optional name) scope new --name <name> targets a named session scope when new replaces an existing open session in that scope, the old one is soft-closed ensure returns the nearest matching active session for the scope, or creates one when none is open. Idempotent — safe to call before every prompt in scripts. close targets current cwd default session close <name> targets current cwd named session show [name] prints stored metadata for that scoped session history [name] prints stored turn history previews (default 20, use --limit ) export [name] --output <path> writes a portable JSON archive containing session state and event history import <archive> creates a fresh local record, reopens the copied session as idle, keeps the provider session id, and clears source-machine process metadata imported sessions must resume that provider session; if the destination agent cannot load it, prompts fail clearly instead of starting an empty conversation import --name <name> and --cwd <dir> override the destination scope; import fails if that scope already has an active session or another local record already uses the same provider session id prune deletes closed session records to reclaim disk space --dry-run previews what would be deleted without touching disk --older-than <days> and --before <date> filter by close time, falling back to last-used time when a record was never explicitly closed --include-history also removes per-session event stream files (otherwise only the JSON record is removed) Global options --agent <command> : raw ACP agent command (escape hatch) --cwd <dir> : working directory for session scope (default: current directory) --approve-all : auto-approve all permission requests --approve-reads : auto-approve reads/searches, prompt for writes (default mode) --deny-all : deny all permission requests --non-interactive-permissions <policy> : when prompting is unavailable, choose deny or fail --permission-policy <json-or-file> / --policy : per-tool ACP permission rules ( autoApprove , autoDeny , escalate , defaultAction ) --format <fmt> : output format ( text , json , quiet ) --json-strict : strict JSON mode; requires --format json and suppresses non-JSON stderr output --suppress-reads : suppress raw read-file contents while preserving the selected format --timeout <seconds> : max wait time (positive number) --ttl <seconds> : queue owner idle TTL before shutdown (default 300 , 0 disables TTL) --model <id> : request an agent model during session creation; non-Claude agents must advertise a model config option or legacy models metadata --system-prompt <text> : replace the agent system prompt. Forwarded to claude-agent-acp via ACP _meta.systemPrompt ; persisted in session_options.system_prompt so reuse keeps the override. Other agents ignore the field. --append-system-prompt <text> : append text to the agent system prompt. Forwarded to claude-agent-acp via ACP _meta.systemPrompt.append ; same persistence rules as --system-prompt . --allowed-tools <list> : comma-separated tool whitelist (use "" for no tools) --max-turns <count> : cap session turn count --prompt-retries <count> : retry failed prompt turns on transient errors (default 0 ) --no-fs : advertise both ACP filesystem capabilities as disabled so compatible agents use their native file operations --no-terminal : do not advertise the ACP terminal capability — useful for review-only or sandboxed agent invocations