gem-hunter
Language: TypeScript
Headless CLI client for stateful Agent Client Protocol (ACP) sessions
acpx is a headless command-line client for the Agent Client Protocol (ACP). It gives agents, orchestrators, and developers one structured interface for persistent sessions, one-shot runs, permissions, and machine-readable output across ACP-compatible coding agents.
$ acpx codex sessions new <session-id> $ acpx codex "summarize this repository" [tool] Read README.md (completed) This repository contains ... [done] end_turn
Note
acpx is pre-1.0. Treat its CLI and runtime interfaces as evolving.
Install the published npm package globally:
npm install -g acpx@latest
acpx requires Node.js 22.13 or newer. To try it without a global install, prefix a command with npx acpx@latest instead. See the install guide for adapter prerequisites, updates, and source builds.
Install and authenticate the coding agent you want to use, then create a session in your project and send it a prompt:
acpx codex sessions new
acpx codex "find the slowest test and explain why"The session is scoped to the current repository and persists across invocations. Creating sessions explicitly prevents automation from starting an unexpected conversation. The quickstart continues with named sessions, one-shot runs, history, and JSON output.
These 30 built-in launch profiles share one command shape. Each guide covers the required CLI or adapter, authentication, and capability limits. Ante is experimental.
| Agent | Command | |
|---|---|---|
 |
Pi | acpx pi … |
 |
OpenClaw | acpx openclaw … |
 |
Codex | acpx codex … |
 |
Claude Code | acpx claude … |
 |
Gemini CLI | acpx gemini … |
 |
Cursor | acpx cursor … |
 |
GitHub Copilot | acpx copilot … |
 |
Ante | acpx ante … |
 |
Antigravity | acpx antigravity … |
 |
DeepSeek Harness | acpx deepseek-harness … |
 |
Devin | acpx devin … |
 |
Factory Droid | acpx droid … |
 |
fast-agent | acpx fast-agent … |
 |
fx | acpx fx … |
 |
Grok Build | acpx grok-build … |
 |
Goose | acpx goose … |
 |
iFlow | acpx iflow … |
 |
Junie | acpx junie … |
 |
Kilocode | acpx kilocode … |
 |
Kimi | acpx kimi … |
 |
Kiro | acpx kiro … |
 |
MCode | acpx mcode … |
 |
Mux | acpx mux … |
 |
Octomind | acpx octomind … |
 |
OpenCode | acpx opencode … |
 |
Poolside | acpx pool … |
 |
Qoder | acpx qoder … |
 |
Qwen Code | acpx qwen … |
 |
Trae | acpx trae … |
 |
ZeroClaw | acpx zeroclaw … |
Need another ACP server? Use acpx --agent '<command>' … or configure a custom agent. See the agent registry for adapter commands and aliases. Logo credits.
Persistent sessions keep context between prompts, support parallel named workstreams, and queue follow-up prompts when a turn is already running. Use exec when you want a stateless run with no saved session.
acpx codex sessions new --name backend acpx codex -s backend "trace the checkout timeout" acpx codex exec "summarize this repository" acpx --model gpt-5.4 codex exec --config-option reasoning_effort=high "review this repository"
Session state lives under ~/.acpx/. The sessions guide covers scope, queue ownership, reconnects, export/import, cancellation, and cleanup.
Text output is the default. --format json emits NDJSON ACP events for automation, while --format quiet prints only the final assistant text. Output events retain structured thinking, tool calls, diffs, and completion state instead of terminal escape sequences.
Permission modes range from read approval to explicit deny or approve-all policies. Use --cwd to set the session scope and filesystem boundary. Global and project JSON configuration can provide defaults; command-line flags take precedence.
For multi-step work, acpx flow run executes TypeScript workflows that combine ACP turns with deterministic actions, decisions, computation, and checkpoints. The package also exports acpx/runtime and acpx/flows for applications that need session and workflow primitives without shelling out.
Use createSharedAcpRuntime() when an application and CLI processes need to share one local session owner.
Start with the flows guide, then use the examples and architecture notes for deeper integrations.
The full documentation is also available at acpx.sh.
pnpm install --frozen-lockfile pnpm run check pnpm run check:docs
See CONTRIBUTING.md for contribution and review guidance.
MIT. See LICENSE.