# CodeGrid Agent Bus — let your agents talk to each other

The Agent Bus lets one agent in CodeGrid **message and read another agent's pane** — natively, no tmux. Claude can hand a task to Codex, read its reply, and keep going. Both stay visible side‑by‑side on the canvas.

It's a tiny MCP server (`agent-bus-mcp.cjs`, ships with CodeGrid) that exposes three tools to your agents:

| Tool | What it does |
|------|--------------|
| `list_agents` | Lists every pane CodeGrid is running (session_id, pane #, command, status). |
| `read_pane` | Reads the recent output of a pane (ANSI‑stripped). |
| `message_agent` | Types a message into another agent's pane (and presses Enter). |

---

## 1. Install it (pick one)

> You only need to do this once per machine. New agent panes pick the tools up automatically afterward.

### Easiest — one command
Find the bundled script and run its installer (it auto‑detects Claude, Codex, Gemini, and Cursor):

```bash
# Installed app:
node "/Applications/CodeGrid.app/Contents/Resources/resources/agent-bus-mcp.cjs" setup
# Running from source:
node "<repo>/src-tauri/resources/agent-bus-mcp.cjs" setup
```

You'll see a ✓ next to each agent it configured. Done.

### Let an agent install it for you
Paste this into any agent running inside CodeGrid (Claude, Codex, …):

```
You're running inside CodeGrid. Install the CodeGrid Agent Bus so agents can
talk to each other. Run this in the shell and report the output:

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

(If that path doesn't exist, find the file with:
  find /Applications "$HOME" -name agent-bus-mcp.cjs 2>/dev/null | head -1
and run `node "<that path>" setup`.)

Then tell me it's installed and that I should open fresh agent panes.
```

### Manual — paste the config yourself
Run `node "<path>/agent-bus-mcp.cjs" print-config` to print ready‑to‑paste snippets, or use these (replace the path with your actual one):

**Claude Code** → `~/.claude.json`, **Gemini CLI** → `~/.gemini/settings.json`, **Cursor** → `~/.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "codegrid-agent-bus": {
      "command": "node",
      "args": ["/path/to/agent-bus-mcp.cjs"]
    }
  }
}
```

**Codex CLI** → `~/.codex/config.toml`:
```toml
[mcp_servers.codegrid-agent-bus]
command = "node"
args = ["/path/to/agent-bus-mcp.cjs"]
```
(or: `codex mcp add codegrid-agent-bus -- node /path/to/agent-bus-mcp.cjs`)

---

## 2. Verify it's loaded
In an agent pane, run `/mcp` (Claude Code / Codex) and look for **`codegrid-agent-bus`** with the three tools. If it's missing, that pane started before install — close it (`Cmd+W`) and open a fresh one (`Cmd+N`).

---

## 3. Use it
1. Open the agents you want as panes (`Cmd+N` → pick Claude / Codex / Gemini).
2. Click **AUTO** (top‑right of the canvas) to tile them side‑by‑side. (Lost a pane? Hit **FIT**.)
3. In one agent, just ask in plain English — it calls the tools for you:

```
List the CodeGrid agents, then ask the Codex pane to implement <feature>.
Wait for it, read its pane, and review what it did.
```

You'll watch the message get typed into the other pane and the reply read back. That's two agents reasoning together.

> Tip: you never type `list_agents` yourself — it's a tool the agent invokes. You talk to the agent in English; it does the tool calls.

---

## Troubleshooting
- **"Can't reach CodeGrid"** → the CodeGrid app must be running (the bus talks to it over a local socket at `~/.codegrid/socket`).
- **Tools missing in `/mcp`** → install (above), then open a fresh pane.
- **Agent typed into the wrong pane** → tell it the exact `session_id` from `list_agents`.

See also: [`agent-bus-skill.md`](./agent-bus-skill.md) — drop it into your agent's instructions so it knows *how* to collaborate well.
