a2a-pane

<!-- markdownlint-disable-next-line MD041 --> <a id="top"></a>

<img src="images/a2a_banner.png" alt="codetyper.a2a banner" width="100%">

<img src="images/a2a_logo.png" alt="codetyper.a2a logo" width="120">

<h1>codetyper.a2a</h1>

<a href="https://github.com/CarGDev/codetyper.a2a/releases"><img src="https://img.shields.io/github/v/release/CarGDev/codetyper.a2a?style=for-the-badge&label=release" alt="Latest release"></a> <img src="https://img.shields.io/badge/version-2.1.17-2ac3de?style=for-the-badge" alt="Version 2.1.17"> <img src="https://img.shields.io/badge/Rust-1.85%2B-f74c00?style=for-the-badge&logo=rust&logoColor=white" alt="Rust 1.85+"> <img src="https://img.shields.io/badge/macOS%20%C2%B7%20Linux-7aa2f7?style=for-the-badge" alt="Platform"> <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg?style=for-the-badge" alt="License: Apache 2.0"></a>

<a href="#use"><strong>Use</strong></a> &bull; <a href="#install"><strong>Install</strong></a> &bull; <a href="a2a/PROTOCOL.md"><strong>Protocol</strong></a> &bull; <a href="CHANGELOG.md"><strong>Changelog</strong></a> &bull; <a href="https://cargdev.io/"><strong>Website</strong></a> &bull; <a href="https://cargdev.io/blog"><strong>Blog</strong></a>

Your agents work one at a time and report only to you. A single long session carries everything, forgets it on compaction, and has no second opinion. <strong>codetyper.a2a gives each agent its own session, a task board to talk through, and a dispatcher that wakes the right one.</strong> An orchestrator plans, routes and delegates; the result comes back to the session that asked. One Rust binary, no Node.

_{<strong>WORKS WITH</strong> <a href="https://opencode.ai">opencode v2</a> &middot; speaks the task model of the <a href="https://github.com/a2aproject/A2A">Agent2Agent (A2A) protocol</a> &middot; macOS and Linux &middot; needs tmux}

Use

<img src="images/oc-running.gif" alt="opencode running with a2a: the orchestrator sends tasks, agents open as tabs, the status tab follows along" width="100%">

Start a tmux session first (a2a needs tmux), then run opencode in it:

tmux
opencode        # or: oc

Whenever opencode starts, the tabs plugin runs oc ensure: the dispatcher is started if needed and a detached a2a-status tab opens with the live status (outside tmux it stops with a message instead). No alias needed (codetypera2a init --shell only adds alias opencode='oc', which does the same through oc).

opencode opens on the orchestrator. Ask it for something; it plans with plan, routes with brain, sends tasks with a2a_send_message and ends its turn. The dispatcher opens the assignee's own session (first time only) and the tabs plugin shows it as a new tab; when the agent finishes, the orchestrator's tab is woken with the result. Switch tabs with Ctrl+Tab.

oc stats looks like this:

<img src="images/oc-stats.png" alt="oc stats: agents sorted by tokens, with share bars, cost and average duration" width="100%">

oc stats --model (alias --models) gives the same view per model, with one titled table per tool (opencode, claude code); this is the opencode table:

<img src="images/oc-stats-models.png" alt="oc stats --models: models sorted by tokens, with share bars, cost, turns, tasks and agents" width="100%">

a2a needs tmux (one tab per agent): oc refuses to start when tmux is not installed or the pane is not inside it. opencode's own flags and plain subcommands (models, run, --version) still work without it.

Inside opencode (the panels plugin)

The plugin adds a few things to the opencode TUI (they come from plugins/a2a/panels.tsx; if they do not show up, the tabs still work):

• Sidebar: a progress bar (██████────── 6.0 / 12) and one row per task with a state symbol, the agent in its own colour (the color: of its agent file) and a ⚠ hop cap marker.
• Footer: a2a ● N open · ~$cost · tokens today.
• Banner above the prompt when a task waits for you or a context hit the hop cap.
• Notifications: a toast and, with the window in the background, a system notification and sound when a task needs you, finishes or fails.
• Slash commands: /a2a-answer (pick one of the numbered options of an input-required task, or write your own), /a2a-continue and /a2a-cancel.

Plans and small chunks

The orchestrator makes work go plan, design, task, implementation, and each implementation task is one work unit of at most 400 changed lines with its tests and docs (a migration that cannot be split is the only exception). Plans are saved to Engram first (a2a/plans/<project>/<slug>); when Engram is not available they are files in ~/.config/opencode/plans/<project>/<number>/ (plan.md, design.md, tasks.md; <number> is the next free integer) or .opencode/plans/<slug>/ in the project.

Protocol details: a2a/PROTOCOL.md.

How a task travels

<img src="images/a2a_flow.jpeg" alt="Flow of a task: user, orchestrator, dispatcher, hub, specialist agents and back" width="100%">

Like the A2A protocol it borrows from, a task has an id, a contextId, messages made of parts, and a state (submitted, working, input-required, completed, failed). The hub keeps them in SQLite and exposes them to agents as MCP tools (a2a_*), so no agent needs to know how another one is built. The wire protocol of the A2A project (HTTP agent cards and JSON-RPC) is not implemented here; this hub is the local, opencode-native version of the same idea.

Harness engineering

codetyper.a2a is a small agent harness: everything around the model (prompts, tools, memory, delegation, checks) is plain files you can read and edit. The design follows the practices in Google Research's harness2 and the awesome-harness-engineering list:

Install

Requirements

• macOS or Linux (it uses kill, ps, symlinks and process groups; Windows is not supported).
• opencode v2 (developed against 2.0.32). Check with opencode --version. Or Claude Code (tested with 2.1.310): see Claude Code below.
• A Rust toolchain (edition 2024, so Rust 1.85 or newer) to build it: brew install rust or rustup. SQLite is bundled, nothing else to install.
• tmux: a2a opens one tab per agent and the live a2a-status window in tmux, so oc and the plugin refuse to start without it (brew install tmux, then run opencode inside a tmux session).
• Optional: the companion MCP tools below.

Option A: Homebrew

The formula lives in the tap CarGDev/homebrew-codetypera2a. Homebrew installs the Rust toolchain it needs to build, so you do not need cargo or a clone:

brew install CarGDev/codetypera2a/codetypera2a
codetypera2a --version        # codetypera2a 2.1.17

Update later with brew update && brew upgrade codetypera2a. To build the latest master instead of the last release: brew install --HEAD CarGDev/codetypera2a/codetypera2a.

If you previously ran cargo install codetypera2a, remove it first (cargo uninstall codetypera2a), otherwise ~/.cargo/bin can shadow the Homebrew binary in your PATH. If the binary moved (for example from cargo to Homebrew), you do not have to edit anything by hand: codetypera2a init or any oc run repairs a dead a2a path in opencode.jsonc and a2a/codetypera2a.path by itself (a backup is kept as opencode.jsonc.bak-a2a).

Option B: download the repo

git clone https://git.cargdev.io/CarGDev/codetyper.a2a.git
cd codetyper.a2a
cargo install --path . --force        # installs codetypera2a into ~/.cargo/bin

Or without cloning: cargo install --git https://git.cargdev.io/CarGDev/codetyper.a2a.git --force. Make sure ~/.cargo/bin is on your PATH.

Then, on either path

codetypera2a init --shell     # install the agents/commands/plugin/MCP entries; --shell adds alias opencode='oc'

Restart opencode (or run opencode reload), then check:

codetypera2a help             # the binary runs
oc status                     # dispatcher: running (it is started by the a2a MCP server)

init is safe to re-run (existing files are skipped unless --force). After upgrading the binary, codetypera2a init --md-only (alias codetypera2a update) refreshes only the agent, command and PROTOCOL markdown and keeps your saved models. Useful options: --tools runs the companion tools' own opencode setup first (engram setup opencode, codegraph install), --no-link skips the oc symlink, --dir <path> / $OPENCODE_CONFIG_DIR targets another config dir.

Claude Code

init can set up Claude Code too. On a terminal it opens a screen that lists the tools it knows, marks the ones it found and lets you pick (space toggles, a all, enter confirms, esc cancels); tools it cannot set up yet are listed as "coming soon":

Which agents should codetypera2a configure?

› ■ Claude Code (detected) — global only
  ■ opencode (detected) — global only
  □ Codex CLI (coming soon)
  □ Cursor (coming soon)
  ...

codetypera2a init is the one command: whatever you pick (or it detects with --yes or without a terminal; opencode when it finds none) is set up completely, with nothing left to run by hand. --claude or --opencode limit it to one tool and give the same result as picking only that tool on the screen; --all does both.

The footer reads like a2a ● · 2 tasks: orchestrator>coder, coder>tester · 1 subagent: Explore: whether the dispatcher is up, the hub tasks in flight (from/to) and the subagents Claude Code is running right now. It is oc statusline, a single fast line that reads the hub read-only and exits 0 whatever it is given; the two hooks run oc statusline --hook start|stop, which keep one small file per running subagent in ~/.codetypera2a/statusline-subagents/ (entries older than 10 minutes are ignored). To turn it off, remove the statusLine key and the four oc statusline hooks from settings.json; init re-adds them on its next run unless you already have a status line of your own. A hook or status line of ours whose binary path is gone (the binary moved) is repaired on the next run; yours are never touched.

Re-running is safe and also an upgrade. init remembers what it wrote in <claude dir>/.a2a-manifest.json. On a rerun a file that is missing is written, a file you did not edit is replaced when this release changed it, and a file you edited is kept and named in one line (--force replaces those too). Files from an install made before the manifest existed are replaced once, and the old copy is kept next to them as <file>.bak-a2a. An up-to-date install writes 0 files.

It is the same source files as for opencode, so there is nothing extra to maintain. --claude-dir <path> or $CLAUDE_CONFIG_DIR target another config dir (its MCP file is then <dir>/.claude.json, which Claude Code reads when started with CLAUDE_CONFIG_DIR=<dir>). codetypera2a update --claude refreshes the converted markdown by the same rules.

Agents that work by themselves. Start the dispatcher with DISPATCH_BACKEND=claude (all agents) or DISPATCH_BACKEND_<AGENT>=claude (one agent, name upper-cased, other characters _, e.g. DISPATCH_BACKEND_CODE_REVIEWER=claude); CLAUDE_BIN points at another claude. Without it nothing changes: opencode runs every agent. A task sent to such an agent runs one headless turn in the project folder (claude -p --agent <name> --session-id <uuid>, later --resume <uuid>, --allowedTools from the agent's tools: plus mcp__a2a__*), with the same rules as for opencode: one wake per task and status message, hop cap, retries, stall check. A failed turn (non-zero exit or an error result) fails the task with agent_error:, oc cancel stops a running turn, oc status shows claude turns running, and oc stats --model counts the turns from their transcripts (the dispatcher does not record them, so nothing is counted twice). Set DISPATCH_BACKEND_ORCHESTRATOR=opencode if your orchestrator runs in opencode while the rest runs in Claude Code. The UserPromptSubmit hook (oc statusline --hook inbox) adds the finished results to your next prompt in an interactive Claude Code session and marks them seen; set A2A_REQUESTER if your requester is not orchestrator.

Claude Code starts on the orchestrator by itself: init writes "agent": "orchestrator" to <claude dir>/settings.json (user scope, every project) when the file has no agent key and agents/orchestrator.md is installed. An agent you already set is kept (init prints a note); a project's .claude/settings.json or claude --agent <name> still wins. init --no-default-agent skips it; to undo it, delete the agent line (the original file is saved as settings.json.bak-a2a).

Check it: claude mcp list shows a2a, and a new claude session opens on the orchestrator (its stream-json init event lists only the orchestrator's tools). Every agent also works as a subagent of any Claude Code session.

Known limits:

• An interactive Claude Code session is never woken by the dispatcher (a headless claude -p cannot inject into it). Results reach it on its next prompt through the UserPromptSubmit hook and the N results waiting part of the footer, so an orchestrator that must react the moment a task finishes still works best in opencode.
• The opencode tabs plugin has no Claude Code version; the A2A pane below is the Claude Code counterpart of the panels, and oc status and oc watch still work from a shell.
• Agents run on Claude only when routed there (DISPATCH_BACKEND / DISPATCH_BACKEND_<AGENT>); the default stays opencode.
• To keep the two runtimes apart, set DISPATCH_ONLY=claude (or opencode) for the hub and the dispatcher: the other runtime is never started or woken and new tasks route to the chosen one.
• The plan agent and the /plan-* commands still look for plans in .opencode/plans/.

The A2A pane (Claude Code)

init --claude also writes a Claude Code "mod" (a plugin of function hooks, plugins/claude-a2a/ in this repo, plugin name a2a-pane) into a local marketplace folder, ~/.claude/a2a-marketplace/ (or <dir>/a2a-marketplace/ for --claude-dir / $CLAUDE_CONFIG_DIR). Once enabled it polls oc status --json and oc messages --json every 4 seconds and shows:

• the dispatcher dot, then one row per task (? 1a2b3c4d orchestrator -> code-reviewer input-required, coloured by state) with the last three messages of that task under it;
• for every task that waits for you, a highlighted "Waiting for you" block with the question, one button per numbered option (press it to run oc answer <task> <option>), and an input to type your own answer;
• /a2a opens or closes the pane.

The pane docks beside the chat from about 110 to 144 columns; below that, or while it is closed, a one-line band above the prompt (a2a ● 2 open · 1 waiting: 1a2b3c4d code-reviewer: Which branch?) takes its place, and the footer status line is unchanged. In a terminal that is too narrow /a2a still opens it inline.

init also runs claude plugin marketplace add and claude plugin install a2a-pane@codetypera2a --scope user --config exe=<binary> itself (against the same config dir: CLAUDE_CONFIG_DIR is passed to the child), skipping a step that is already done and running claude plugin update when the pane version changed. If claude is missing or a step fails, init prints one failure line with the exact commands and carries on. Restart Claude Code to see the pane. exe is the binary the mod runs (<exe> oc status --json); change it later in /config (plugin a2a-pane).

tmux. Inside tmux, Claude Code behaves like opencode with its tabs plugin. A SessionStart hook (oc statusline --hook ensure) starts the dispatcher and opens the detached a2a-status window when a session starts; it prints nothing, returns at once and does nothing outside tmux. With DISPATCH_BACKEND=claude, ea