`acpx` is a command-line interface (CLI) client designed to facilitate communication between AI agents and coding agents using the Agent Client Protocol (ACP). Its primary purpose is to provide a structured and reliable way for agents to interact, moving away from less efficient methods like scraping output from terminal sessions. This tool is particularly useful for orchestrating coding tasks, allowing AI agents to delegate complex coding projects to specialized coding agents.
The core functionality of `acpx` revolves around managing stateful ACP sessions. It offers persistent sessions, enabling multi-turn conversations that persist across multiple invocations of the CLI. These sessions are scoped per repository, ensuring that context is maintained within the relevant project directory. Furthermore, `acpx` supports named sessions, allowing users to run parallel workstreams within the same repository, such as separate sessions for backend and frontend development.
A key feature is its prompt queueing system. When a prompt is submitted while another is already running, it is automatically queued and executed in order. This ensures that tasks are processed sequentially, preventing conflicts and maintaining a logical flow of work. The `cancel` command provides a cooperative mechanism to stop running prompts, sending an ACP `session/cancel` message without disrupting the session state. `acpx` also implements a soft-close lifecycle, allowing sessions to be closed without deleting the history, preserving valuable context for future interactions.
`acpx` offers several features to enhance usability and control. The `--no-wait` flag allows users to submit prompts and immediately return to the command line, while the `--ttl` flag controls the time-to-live of queue owners. The tool also provides graceful cancel functionality, sending an ACP `session/cancel` signal before resorting to a force-kill fallback. Session controls, such as `set-mode` and `set <key> <value>`, enable users to configure session behavior. Crash reconnect is another important feature, automatically reloading sessions if an agent process dies.
The CLI supports various input methods, including prompts from files and standard input. Configuration files, both global and project-specific, allow for customization of agent behavior and settings. The tool also provides commands for inspecting session history and status, offering insights into ongoing and past activities. Stable `fs/*` and `terminal/*` handlers with permission controls and cwd sandboxing are available for client methods. Authentication is supported through environment variables or configuration files.
`acpx` supports structured output, providing typed ACP messages instead of requiring users to parse raw terminal output. It includes a built-in registry of ACP agents, including support for Pi, OpenClaw, Codex, Claude, Gemini, Cursor, Copilot, Droid, iFlow, Kilocode, Kimi, Kiro, Opencode, Qoder, Qwen, and Trae. Users can also specify custom ACP servers using the `--agent` flag.
Beyond basic prompt execution, `acpx` introduces experimental flows. These flows, defined in TypeScript modules, allow for multi-step ACP workflows. They support `acp` steps for model-shaped work, `action` steps for deterministic mechanics, `compute` steps for local routing, and `checkpoint` steps for pausing. This enables complex, automated coding workflows. The tool also offers various output formats, including text, JSON, and quiet modes, and supports features like suppressing read payloads. Overall, `acpx` is a powerful tool for streamlining agent-to-agent communication and automating coding tasks.
