Summary

acpx provides a headless CLI client for the Agent Client Protocol (ACP), enabling AI agents and orchestrators to communicate with coding agents via a structured protocol rather than PTY scraping. It targets AI developers and users of coding agents like Codex, Claude, and Gemini, offering a robust and persistent communication layer for agent-to-agent interactions. The primary benefit is a stable, feature-rich interface for managing complex coding tasks and conversations programmatically.

How It Works

The tool leverages the Agent Client Protocol (ACP) to establish stateful, persistent sessions scoped to repositories. It manages a prompt queue, allowing multiple requests to be processed sequentially, and supports cooperative cancellation commands. acpx features automatic crash recovery, reloading sessions if the agent process dies, and a soft-close lifecycle that preserves history. Communication relies on structured, typed ACP messages for actions like tool calls and diffs, moving beyond raw terminal output.

Quick Start & Requirements

• Install: npm install -g acpx@latest or run via npx acpx@latest.
• Prerequisites: Requires underlying coding agents (e.g., Codex CLI, Claude Code, Gemini CLI, OpenCode, Pi Coding Agent). acpx auto-downloads necessary ACP adapters.
• Documentation:
  • Skill Reference: https://raw.githubusercontent.com/openclaw/acpx/main/skills/acpx/SKILL.md
  • CLI Reference: https://raw.githubusercontent.com/openclaw/acpx/main/docs/CLI.md

Highlighted Details

• Persistent, named sessions per repository for multi-turn conversations and parallel workstreams.
• Prompt queuing, cooperative cancel command, and queue owner TTL for managing agent tasks.
• Crash reconnect functionality automatically reloads sessions upon agent process failure.
• Structured output (typed ACP messages) and stable fs/*, terminal/* handlers with permission controls.
• Built-in support for multiple agents (Codex, Claude, Gemini, etc.) with an --agent escape hatch for custom ACP servers.

Maintenance & Community

No specific details regarding maintainers, community channels (like Discord/Slack), or roadmap were found in the provided README.

Licensing & Compatibility

The project is released under the MIT license, permitting commercial use and integration into closed-source projects.

Limitations & Caveats

acpx is currently in alpha, and its CLI and runtime interfaces are subject to change, potentially causing downstream breakage until stabilization.