ACP: The Missing Protocol for Coding Agent-to-Agent Communication

·https://github.com/openclaw/acpx
repoaiagent-loopsclitypescriptinfrastructureprotocolorchestration

Directly addresses the PTY-scraping hack in system-bus LLM inference — gives a structured, session-aware protocol for delegating work to pi, codex, and claude from orchestrators like the gateway and agent-loop

acpx is a headless CLI client for the Agent Client Protocol (ACP) — a structured protocol that lets AI orchestrators delegate work to coding agents without scraping PTY sessions. Instead of parsing ANSI escape codes and hoping the terminal output stays legible, you get typed messages: thinking blocks, tool calls, diffs, completion signals. The protocol is the interface, not the screen. It supports Codex, Claude Code, Gemini CLI, OpenCode, OpenClaw, and — directly relevant here — pi.

The feature set reads like a spec for exactly what you’d want if you were building an agent orchestration layer. Persistent sessions scoped per repo. Named sessions for parallel workstreams (-s backend, -s frontend). Prompt queueing when an agent is already running. Cooperative cancel via session/cancel — not a force-kill, a graceful handshake. Crash reconnect when the underlying process dies. Fire-and-forget mode with --no-wait. This is the contract you’d need if the gateway wanted to hand off a coding task to pi durably rather than hoping a PTY doesn’t garble the output halfway through.

The openclaw GitHub org is worth paying attention to — it’s distinct from joelclaw but building infrastructure in the same general space. The ACP spec is a separate initiative that acpx implements as its reference client. It’s in alpha and the interfaces will shift, but the direction is clear: structured agent-to-agent communication is becoming a real protocol, not just a pattern people bolt together per project.

The joelclaw connection is immediate. System-bus functions already shell to pi -p --no-session --no-extensions for inference — that’s a one-shot, stateless, ad-hoc invocation. If ACP stabilizes and pi ships a solid ACP server, acpx is the path from that hack to a session-aware, queueable, cancellable coding agent interface that the agent-loop infrastructure could actually rely on. Worth watching as ADR-0157 evolves.

Key Ideas

  • ACP (Agent Client Protocol) is a structured protocol for agent-to-agent CLI communication — typed messages instead of ANSI terminal scraping
  • Persistent, named sessions scoped per repo with parallel workstream support (-s backend, -s frontend) — session state lives in ~/.acpx/
  • Prompt queueing with cooperative cancel — submit work while an agent is running; Ctrl+C sends session/cancel before force-kill; --no-wait for fire-and-forget dispatch
  • Crash reconnect — dead agent processes are detected and sessions reload automatically, no manual intervention
  • One CLI surface for Codex, Claude Code, Gemini CLI, pi, OpenCode, OpenClaw
  • acpx exec for one-shot stateless tasks without session overhead — equivalent to the current pi --no-session invocation pattern
  • Skill injection pattern — acpx --skill install acpx loads the CLI reference into the agent’s context; same concept as joelclaw’s skill system
  • The openclaw org is building ACP-adjacent infrastructure worth monitoring as the protocol matures

Links

← All discoveries