The Agent Bus

Let your agents work together — one agent can message and read another agent's pane, natively, with no tmux.

What it is

The Agent Bus is a tiny MCP server that ships with CodeGrid (agent-bus-mcp.cjs). It gives your agents three tools so they can collaborate: Claude can hand a task to Codex, read its reply, and keep going — all while both stay visible side by side on the canvas.

NOTE
It talks to CodeGrid over a local socket — no tmux, no extra terminal multiplexer, no daemons. CodeGrid already owns the panes, so the bus just exposes them.

The tools

  • list_agents — every pane CodeGrid is running: session_id, pane #, command, status, directory.
  • read_pane(session_id) — recent output of a pane (ANSI-stripped).
  • message_agent(session_id, text) — types a message into another agent's pane and presses Enter.

Install (one click)

The fastest path: the onboarding's "Enable collaboration" button configures every agent for you. To do it manually, run the bundled installer — it auto-detects Claude, Codex, Gemini, and Cursor:

terminal
node "/Applications/CodeGrid.app/Contents/Resources/resources/agent-bus-mcp.cjs" setup

Prefer to paste the config yourself? Print ready-to-use snippets:

terminal
node "<path>/agent-bus-mcp.cjs" print-config

Manual config (replace the path with your own):

Claude (~/.claude.json) · Gemini (~/.gemini/settings.json) · Cursor (~/.cursor/mcp.json)
{
  "mcpServers": {
    "codegrid-agent-bus": {
      "command": "node",
      "args": ["/path/to/agent-bus-mcp.cjs"]
    }
  }
}
Codex (~/.codex/config.toml)
[mcp_servers.codegrid-agent-bus]
command = "node"
args = ["/path/to/agent-bus-mcp.cjs"]

Verify

In an agent pane, run /mcp and look for codegrid-agent-bus with the three tools. Missing? That pane started before install — close it (⌘W) and open a fresh one (⌘N).

Use it

  1. Open the agents you want as panes, then click AUTO to see them side by side.
  2. In one agent, ask in plain English — it calls the tools for you:
paste into the Claude pane
Use codegrid-agent-bus: list_agents, find the Codex pane, ask it to
implement <feature>, then read_pane its reply and review what it did.

You'll watch the message get typed into the Codex pane and the reply read back — two agents reasoning together.

TIP
You never call list_agents yourself — it's a tool the agent invokes. You talk to the agent in English; it does the tool calls. Address agents by the session_id from list_agents, never by guessing.

Patterns

  • Delegate — Claude → message Codex to implement → poll until done → summarize.
  • Review — finish a change, ask another agent to review the diff, apply the feedback.
  • Pipeline — Gemini researches → you implement → Codex reviews. Each hand-off is read → message → read.
  • Monitor — read a build/test/shell pane to react to its output.

Teach your agents to do this well with a collaboration skill.

Troubleshooting

  • "Can't reach CodeGrid" — the app must be running (the bus uses ~/.codegrid/socket).
  • Tools missing — install (above), then open a fresh pane.
  • Typed into the wrong pane — give the agent the exact session_id from list_agents.
Previous← Broadcast modeNextWriting a collaboration skill →