a2abridge

The problem

Multiple coding agents now run in parallel — Claude Code over here, Codex CLI over there, Cursor, Cline, Continue, Gemini CLI, Antigravity CLI. They live in the same codebase but they don’t talk. Every breaking contract change ends up re-discovered by each agent the slow way.

a2abridge wraps each agent into a standard A2A 1.0 peer so they can message each other proactively.

Architecture

• A local directory service on 127.0.0.1:7777, installed as a user-level system service (launchd, systemd —user or a Windows Service).
• A per-agent bridge that is both an MCP server for the IDE and an A2A peer with its own Agent Card.
• Each agent has a session-stable self-label of the form <basename-cwd>-<4hex>, so peers know who is speaking.
• An inbox hook injects unread peer messages at the top of the agent’s next prompt.
• Optional: mDNS / DNS-SD discovery on the LAN and cross-machine federation over mTLS with ed25519 certificates.

Version 4.0 (4.0.0–4.0.2, 2026-09-15 – 2026-09-21)

• A2A 1.0 through the official Go SDK. The hand-written protocol layer of 3.x is replaced by a2a-go v2.5.0. Bridges serve the JSON-RPC and HTTP+JSON bindings with SSE streaming and push notifications.
• Breaking change. 3.x and 4.x bridges are not wire-compatible, so every bridge on a mesh is upgraded together. The non-spec /v1/ REST API and legacy method names are removed. The Go module path is now github.com/vbcherepanov/a2abridge/v4.
• Added: Antigravity CLI support, a multi-arch Docker image on ghcr.io (linux/amd64 and linux/arm64), and a build target that runs the bridge’s HTTP stack against the official A2A TCK scenarios.
• 4.0.1 fixes the version reported by binaries installed with go install.
• 4.0.2 (2026-09-21): the one-line installer now detects fresh Codex CLI and Cursor installs, which create their state directory before any config file.
• Conformance: measured on v4.0.1 against the official A2A TCK (JSON-RPC and HTTP+JSON): 157 passed, 6 failed — all six caused by the a2a-go SDK — and 95 skipped, most of them gRPC checks, which the bridge does not serve. The TCK’s reference Python implementation scores 198 passed, 9 failed on the same TCK commit. Interoperates with the official Python a2a-sdk 1.1.0 in both directions (7/7 scenarios). Not a certification — see the conformance report.

Implementation highlights

• Transport: a2a_send_message for fire-and-forget messages, a2a_get_task for follow-ups. Streaming between MCP-hosted peers is deliberately avoided: the streaming RPC’s keep-alive does not match a real LLM turn cycle.
• Hard rules in the bundled skill:
  • INBOUND-first — process unread messages before replying.
  • Self-label every outbound message.
  • Don’t spam: messages are for contract / API / schema / public-behaviour changes. Internal refactors stay quiet.
  • Don’t ask peers to “check inbox” — they have their own hook.
• Request limits: A2A request bodies are capped at 10 MiB, and reading a request is bounded by a one-minute timeout.

Results

MIT-licensed single Go binary for macOS, Linux, Windows and WSL2, published as releases 4.0.0–4.0.2 and as a ghcr.io image. Installs the MCP block into each detected IDE’s config with timestamped backups.

Lessons

• The chat-style metaphor was wrong. Agents need a queue with hooks, not a chat client.
• Following the spec means using the spec’s implementation. Replacing my own protocol layer with the official SDK cost wire compatibility with 3.x, and that trade was worth making.