acpx
Website: https://github.com/openclaw/acpx CLI Tool: acpx Repository: https://github.com/openclaw/acpx Protocol: Agent Client Protocol (ACP)
Description
acpx is a headless CLI client for the Agent Client Protocol (ACP), enabling AI agents to communicate with coding agents (Codex, Claude, Gemini, etc.) over a structured protocol instead of PTY scraping. Built for agent-to-agent communication with persistent sessions, prompt queueing, and structured output.
Install
npm install -g acpx
Or use without installing:
npx acpx@latest
Usage
Basic Prompts (Persistent Session)
# Create a new session first
acpx codex sessions new
# Send prompts (uses saved session)
acpx codex "fix the flaky tests"
acpx claude "refactor the auth module"
acpx gemini "explain this codebase"
One-Shot Mode (No Session)
acpx exec "summarize this repo"
acpx codex exec "one-shot task without saving session"
Named Sessions (Parallel Workstreams)
acpx codex sessions new --name backend
acpx codex sessions new --name frontend
acpx codex -s backend "work on API endpoints"
acpx codex -s frontend "work on React components"
Commands
| Command | Description |
|---|---|
acpx <agent> "prompt" |
Send prompt (default: persistent session) |
acpx <agent> exec "prompt" |
One-shot prompt (no session saved) |
acpx <agent> sessions new |
Create new session |
acpx <agent> sessions list |
List all sessions |
acpx <agent> sessions close |
Close current session |
acpx <agent> sessions show |
Show session metadata |
acpx <agent> sessions history |
Show session history |
acpx <agent> cancel |
Cancel running prompt |
acpx <agent> set-mode <mode> |
Set agent mode (e.g., plan) |
acpx <agent> status |
Check agent process status |
acpx config show |
Show configuration |
acpx config init |
Initialize config file |
Built-in Agents
| Agent | Command Mapping |
|---|---|
codex (default) |
npx @zed-industries/codex-acp |
claude |
npx @zed-industries/claude-agent-acp |
gemini |
gemini |
opencode |
npx opencode-ai |
pi |
npx pi-acp |
Custom agents: unknown names are treated as raw commands, or use --agent <command>.
Global Options
| Option | Description |
|---|---|
--approve-all |
Auto-approve all permissions |
--approve-reads |
Auto-approve reads, prompt for others (default) |
--deny-all |
Deny all permissions |
--format <fmt> |
Output: text (default), json, quiet |
--json-strict |
Strict JSON mode (suppress non-JSON stderr) |
--cwd <dir> |
Working directory |
--timeout <sec> |
Max wait time for response |
--ttl <sec> |
Queue owner idle TTL (default: 300) |
--no-wait |
Queue prompt and return immediately |
-f, --file <path> |
Read prompt from file (- for stdin) |
-s, --session <name> |
Use named session |
--verbose |
Enable verbose logs |
Examples
Delegate Work to Codex
# Start session and fix tests
acpx codex sessions new
acpx codex "find the flaky test and fix it"
Auto-Approve All Operations
acpx --approve-all codex "apply this patch and run tests"
JSON Output for Scripts
acpx --format json codex exec "list all TODO comments" | jq '.items'
Prompt from File
echo "Refactor the database module" > task.txt
acpx codex --file task.txt
Prompt from Stdin
echo "Explain main.py" | acpx codex
cat prompt.md | acpx claude
Cancel Running Prompt
acpx codex cancel
Parallel Sessions
acpx codex sessions new --name api
acpx codex sessions new --name ui
acpx codex -s api "implement REST endpoints"
acpx codex -s ui "build dashboard components"
Fire-and-Forget
acpx codex --no-wait "run the full test suite"
# Returns immediately, prompt queued
Custom Agent
acpx --agent "my-custom-acp-server" "do something"
Session Scoping
Sessions are scoped by:
- Agent command (codex, claude, etc.)
- Working directory (cwd)
- Optional session name (-s)
This means different repos have independent sessions.
Output Modes
text(default): Human-readable streaming output with thinking, tool calls, diffsjson: Structured JSON output for machine consumptionquiet: Minimal output, just final result
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Usage error |
| 3 | Agent error |
| 4 | No session (need sessions new) |
| 5 | Timeout |
Notes
- Sessions persist across invocations - multi-turn conversations work automatically
- Queue-aware - prompts queue when session is busy, no race conditions
- Graceful cancel - Ctrl+C sends ACP
session/cancelbefore force-kill - Crash recovery - dead agent processes are detected and sessions auto-reload
- No PTY scraping - structured ACP messages instead of ANSI parsing
Comments (0)
Add a Comment
No comments yet. Be the first to comment!