# acpx — ACP CLI for Coding Agents > ACP CLI to run coding agents (Codex, Claude Code, etc.) with stateful sessions and reproducible actions. Verified 2653★; pushed 2026-05-14. ## Install Copy the content below into your project: ## Quick Use ```bash npm install -g acpx@latest acpx --help # Run a one-shot prompt with Codex (example from README): acpx codex "fix the tests" # Or run without installing: npx acpx@latest codex "fix the failing tests" ``` ## Intro ACP CLI to run coding agents (Codex, Claude Code, etc.) with stateful sessions and reproducible actions. Verified 2653★; pushed 2026-05-14. **Best for:** Developers who want agent runs to be sessioned, repeatable, and less dependent on raw PTY scraping **Works with:** Node.js; integrates with Codex CLI and Claude Code adapters (see README agent prerequisites) **Setup time:** 6-12 minutes ### Key facts (verified) - GitHub: 2653 stars · 259 forks · pushed 2026-05-14. - License: MIT · owner avatar + repo URL verified via GitHub API. - README-backed entrypoint: `acpx codex`. ## Main - Prefer named sessions per goal (e.g., `api`, `docs`) so you can run parallel agent work without mixing histories. - Use `--file` for long prompts: keep prompt context in version control and avoid copy/paste drift. - Treat `~/.acpx/` as state: back it up or clear it when debugging session issues across projects. - Start with the README “agent prerequisites” list to ensure the underlying agent (Codex/Claude) is installed and reachable. ### README (excerpt)

acpx banner

**acpx** [![npm version](https://img.shields.io/npm/v/acpx.svg)](https://www.npmjs.com/package/acpx) [![npm downloads](https://img.shields.io/npm/dm/acpx.svg)](https://www.npmjs.com/package/acpx) [![CI](https://github.com/openclaw/acpx/actions/workflows/ci.yml/badge.svg)](https://github.com/openclaw/acpx/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js](https://img.shields.io/node/v/acpx.svg)](https://nodejs.org) > ⚠️ `acpx` is in alpha and the CLI/runtime interfaces are likely to change. Anything you build downstream of this might break until it stabilizes. > ACP coverage status: see [ACP Spec Coverage Roadmap](docs/2026-02-19-acp-coverage-roadmap.md). Your agents love acpx! 🤖❤️ They hate having to scrape characters from a PTY session 😤 `acpx` is a headless CLI client for the [Agent Client Protocol (ACP)](https://agentclientprotocol.com), so AI agents and orchestrators can talk to coding agents over a structured protocol instead of PTY scraping. One command surface for Pi, OpenClaw ACP, Codex, Claude, and other ACP-compatible agents. Built for agent-to-agent communication over the command line. - **Persistent sessions**: multi-turn conversations that survive across invocations, scoped per repo - **Named sessions**: run parallel workstreams in the same repo (`-s backend`, `-s frontend`) - **Prompt queueing**: submit prompts while one is already running, they execute in order - **Cooperative cancel command**: `cancel` sends ACP `session/cancel` via queue IPC without tearing down session state - **Soft-close lifecycle**: close sessions without deleting history from disk - **Queue owner TTL**: keep queue owners alive briefly for follow-up prompts (`--ttl`) - **Fire-and-forget**: `--no-wait` queues a prompt and returns immediately - **Graceful cancel**: `Ctrl+C` sends ACP `session/cancel` before force-kill fallback - **Session controls**: `set-mode` and `set ` for `session/set_mode` and `session/set_config_option` - **Crash reconnect**: dead agent processes are detected and sessions are reloaded automatically ### Source-backed notes - README shows installs via `npm install -g acpx@latest` and usage via `npx acpx@latest ...`. - README documents session commands like `acpx codex sessions new` and `acpx codex sessions list`. - README states session state lives under `~/.acpx/` and adapters can be auto-downloaded on first use. ### FAQ - **Do I need a global install?**: No—README shows `npx acpx@latest` for zero-install usage. - **Where does session state live?**: README states it lives under `~/.acpx/` by default. - **Which agents are supported?**: README lists adapters for Codex, Claude Code, and others via ACP. ## Source & Thanks > Created by [openclaw](https://github.com/openclaw). Licensed under MIT. > > [openclaw/acpx](https://github.com/openclaw/acpx) — ⭐ 2653 Thanks to the upstream maintainers and contributors for publishing this work under an open license. --- ## Quick Use ```bash npm install -g acpx@latest acpx --help # Run a one-shot prompt with Codex (example from README): acpx codex "fix the tests" # Or run without installing: npx acpx@latest codex "fix the failing tests" ``` ## Intro acpx 是 ACP 的命令行客户端，用会话+可重放动作把 Codex/Claude Code 等 coding agent 跑得更可控、更稳定；已验证 2653★，更新于 2026-05-14。 **Best for:** 希望把 agent 运行做成可复现会话、减少纯 PTY 抓取依赖的开发者 **Works with:** Node.js；可对接 Codex CLI、Claude Code 等适配器（见 README prerequisites） **Setup time:** 6-12 minutes ### Key facts (verified) - GitHub：2653 stars · 259 forks；最近更新 2026-05-14。 - 许可证：MIT；作者头像与仓库链接均已通过 GitHub API 复核。 - README 中可对照的入口：`acpx codex`。 ## Main - 按目标拆成命名会话（如 `api`/`docs`），让并行 agent 任务不互相污染上下文与历史。 - 长提示词用 `--file` 管理：把上下文放进版本库，避免复制粘贴造成漂移。 - 把 `~/.acpx/` 当作运行态状态：排障时可备份/清理，避免旧会话影响新项目。 - 先按 README 的 prerequisites 检查底层 agent（Codex/Claude）是否安装并可调用。 ### README (excerpt)

acpx banner

**acpx** [![npm version](https://img.shields.io/npm/v/acpx.svg)](https://www.npmjs.com/package/acpx) [![npm downloads](https://img.shields.io/npm/dm/acpx.svg)](https://www.npmjs.com/package/acpx) [![CI](https://github.com/openclaw/acpx/actions/workflows/ci.yml/badge.svg)](https://github.com/openclaw/acpx/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js](https://img.shields.io/node/v/acpx.svg)](https://nodejs.org) > ⚠️ `acpx` is in alpha and the CLI/runtime interfaces are likely to change. Anything you build downstream of this might break until it stabilizes. > ACP coverage status: see [ACP Spec Coverage Roadmap](docs/2026-02-19-acp-coverage-roadmap.md). Your agents love acpx! 🤖❤️ They hate having to scrape characters from a PTY session 😤 `acpx` is a headless CLI client for the [Agent Client Protocol (ACP)](https://agentclientprotocol.com), so AI agents and orchestrators can talk to coding agents over a structured protocol instead of PTY scraping. One command surface for Pi, OpenClaw ACP, Codex, Claude, and other ACP-compatible agents. Built for agent-to-agent communication over the command line. - **Persistent sessions**: multi-turn conversations that survive across invocations, scoped per repo - **Named sessions**: run parallel workstreams in the same repo (`-s backend`, `-s frontend`) - **Prompt queueing**: submit prompts while one is already running, they execute in order - **Cooperative cancel command**: `cancel` sends ACP `session/cancel` via queue IPC without tearing down session state - **Soft-close lifecycle**: close sessions without deleting history from disk - **Queue owner TTL**: keep queue owners alive briefly for follow-up prompts (`--ttl`) - **Fire-and-forget**: `--no-wait` queues a prompt and returns immediately - **Graceful cancel**: `Ctrl+C` sends ACP `session/cancel` before force-kill fallback - **Session controls**: `set-mode` and `set ` for `session/set_mode` and `session/set_config_option` - **Crash reconnect**: dead agent processes are detected and sessions are reloaded automatically ### Source-backed notes - README 给出安装方式 `npm install -g acpx@latest`，也支持 `npx acpx@latest ...` 免安装运行。 - README 列出会话相关命令，如 `acpx codex sessions new` / `sessions list` 等。 - README 提到会话状态存放在 `~/.acpx/`，并且首次使用可自动下载适配器。 ### FAQ - **必须全局安装吗？**：不必须：README 提供 `npx acpx@latest` 的免安装用法。 - **会话状态在哪里？**：README 说明默认在 `~/.acpx/`。 - **支持哪些 agent？**：README 列出 Codex、Claude Code 等适配器，并通过 ACP 统一调用。 ## Source & Thanks > Created by [openclaw](https://github.com/openclaw). Licensed under MIT. > > [openclaw/acpx](https://github.com/openclaw/acpx) — ⭐ 2653 --- Source: https://tokrepo.com/en/workflows/acpx-acp-cli-for-coding-agents Author: Script Depot