# Acpx

> Use acpx as a headless ACP CLI for agent-to-agent communication, including prompt/exec/sessions workflows, session scoping, queueing, permissions, and output formats.

- Skill: `asm3r96/acpx` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add asm3r96/acpx`
- Raw SKILL.md: https://api.skillmd.com/api/skills/asm3r96/acpx/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: asm3r96 (https://skillmd.com/u/asm3r96)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/asm3r96/acpx

---


# 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 output from scripts.

Use it especially for Wave-Driven Development execution after `wave-planner-acpx` is approved.

## What acpx is

`acpx` is a headless, scriptable CLI client for ACP (Agent Client Protocol) designed for agent-to-agent automation without 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 (`cancel`) for in-flight turns
- Session control (`set-mode`, `set <key> <value>`)
- Session metadata/history inspection (`sessions show`, `sessions history`)
- Local agent process checks (`status`)
- Structured output formats (`text`, `json`, `quiet`)
- `--suppress-reads` for cleaner orchestration output
- `--prompt-retries` for retrying transient prompt failures
- Generic model selection via ACP `session/set_model`
- `--model` support for Codex sessions
- Experimental flows runtime and replay-related tooling in `v0.4.0`

## Install

```bash
npm i -g acpx
```

Prefer global install over `npx` for stable session reuse.

## Command model

`prompt` is default.

```bash
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> exec [prompt_options] [prompt_text...]
```

## Built-in agent registry

Friendly names:
- `codex` -> `npx @zed-industries/codex-acp`
- `claude` -> `npx @zed-industries/claude-agent-acp`
- `gemini` -> `gemini`
- `opencode` -> `npx opencode-ai`
- `pi` -> `npx pi-acp`
- `qoder` -> `qodercli --acp`
- `trae` -> `traecli acp serve`

Rules:
- Default agent is `codex`.
- Unknown positional agent tokens are treated as raw commands.
- `--agent <command>` is explicit raw command mode.
- Do not combine positional agent token with `--agent`.

## Core workflows

### Persistent prompt session

```bash
acpx codex 'inspect failing tests and propose fix plan'
acpx codex 'apply minimal fix and run tests'
```

### One-shot exec

```bash
acpx exec 'summarize this repo'
acpx codex exec 'review changed files'
```

### Sessions

```bash
acpx sessions new --name backend
acpx codex -s backend 'fix API pagination bug'
acpx codex sessions history backend --limit 20
acpx codex sessions close backend
```

### Queueing and no-wait

```bash
acpx codex 'run full test suite and investigate failures'
acpx codex --no-wait 'after tests, summarize root causes and next steps'
```

### Structured output for orchestration

```bash
acpx --format json codex exec 'review changed files' > events.ndjson
```

### Retries and quieter logs

```bash
acpx codex --prompt-retries 2 'run targeted tests and summarize failures'
acpx --format json --suppress-reads codex exec 'review changed files'
```

## Wave-Driven orchestration guidance

When running worker agents in waves:

1. Create one named session per worker (`-s <agent-name>`).
2. Send worker prompt with strict ownership boundaries.
3. Require explicit completion marker in each response.
4. Wait for marker before merge.
5. Merge per wave order.
6. Run integration checks before next wave.

Recommended completion marker:
`WAVE {WAVE_ID} / {AGENT_NAME} DONE`

Recommended worker handoff format:
1. Summary
2. Files changed
3. Patch/diffs
4. How to test (commands + expected results)
5. Risks/TODOs/Dependency Notes

## Global options

- `--agent <command>` raw ACP adapter command
- `--cwd <dir>` session scope directory
- `--approve-all` auto-approve all requests
- `--approve-reads` approve reads/searches, prompt for writes
- `--deny-all` deny all requests
- `--model <id>` request a model when supported by the target agent/session
- `--format <fmt>` output: `text`, `json`, `quiet`
- `--suppress-reads` hide raw read/search output when cleaner logs are useful
- `--prompt-retries <count>` retry transient prompt failures automatically
- `--timeout <seconds>` max wait
- `--ttl <seconds>` queue owner idle TTL
- `--verbose` debug logs

Permission flags are mutually exclusive.

## Session behavior

Persistent prompt sessions are scoped by:
- `agentCommand`
- absolute `cwd`
- optional `session` name

Tips:
- Use named sessions for parallel streams in one repo.
- Use `--cwd` carefully; changing cwd changes session scope.
- Use `status` and `sessions show/history` to debug state.

## Practical examples

Parallel named streams:

```bash
acpx codex -s backend 'implement contract types for Wave 0'
acpx claude -s docs 'draft migration notes for Wave 0'
```

Repo-scoped review with permissive mode:

```bash
acpx --cwd ~/repos/shop --approve-all codex -s pr-842 \
  'review PR #842 for regressions and propose minimal patch'
```