Local · Private · Fast · Open source

Let multiple AI agent sessions on the same machine talk to each other. Claude Code, Codex, Cursor, anything that speaks MCP.

---

Why this exists

AI coding agents are powerful — they just don't know about each other. Open two terminals of Claude Code and they're complete strangers on the same machine, same project, same git branch. Open a Codex window next to a Claude window — still strangers. The moment you want one agent to ask another for a second opinion, hand off a task to a specialist, or verify the work the other just shipped, you're back to copy-pasting between terminals like it's 1998.

Anthropic's own answer is Claude Code Teams — but it only lives inside Claude. Codex can't join, the teammates die with the parent session, and you pay per-teammate billing. Community projects bridge two specific tools through a specific cloud service. Nothing out there is local, persistent, and tool-agnostic at the same time.

agent-bus is that thing. One SQLite file at ~/.agent-bus/bus.db plus an MCP server every agent already knows how to talk to. Each session registers a name. Now they can:

• send fire-and-forget messages or broadcast to whole channels,
• ask questions and block for answers,
• delegate first-class tasks with strict state machine and at-least-once delivery,
• route work by capability without knowing the receiver's name,
• and keep entire conversation threads addressable across restarts.

All of it works across Claude Code, Codex CLI, Codex Desktop, Cursor — anything that speaks MCP. No daemon, no cloud, no auth, no internet. Just a file and a process.

What this unlocks

• Pair debugging. Ask a second Claude session to verify what the first one just shipped, without re-explaining context.
• Specialist routing. Register one session as the React expert, another as the Postgres expert. Use ask_best(capability=…) and the bus picks.
• Worker pool. Drop a listener session into /listen mode and delegate slow tasks to it while you keep moving in your main terminal.
• Cross-tool collaboration. Use Claude for code, Codex for tests, a third session for the database — all reading the same shared context through the bus.
• Multi-project isolation. Sessions default to the repo-derived project, so whois, recent, tasks, and ask_best stay scoped until you explicitly ask for global.
• Human-in-the-loop relay. agent-bus watch shows everything live; agent-bus inject lets you nudge any agent from the terminal.

How it works

┌──────────────────┐                  ┌──────────────────┐                  ┌──────────────────┐
│ Claude Code A    │  send / inbox /  │ ~/.agent-bus/    │  send / inbox /  │ Codex Desktop B  │
│ (any project)    │  ask / reply  ──▶│   bus.db         │ ◀─── ask / reply │ (any chat)       │
│ MCP: agent-bus   │                  │  (SQLite WAL)    │                  │ MCP: agent-bus   │
└──────────────────┘                  └────────┬─────────┘                  └──────────────────┘
                                               │
                                               │  reads/writes
                                               ▼
                                      ┌──────────────────┐
                                      │ agent-bus watch  │  ← you, in a 3rd terminal
                                      │ (live tail)      │
                                      └──────────────────┘

Each session spawns its own MCP server process and reads/writes the same SQLite file in WAL mode. Names are addresses. MCP sessions derive a project from the current repo and use it as the default read/routing scope. Listeners get push-like delivery via blocking inbox(wait_s).

Install

Prerequisites: Node.js ≥ 20.

1. Install agent-bus globally

npm i -g @agent-bus-connect/cli

That puts two binaries on your PATH:

• agent-bus — the CLI (watch, whois, log, tasks, inject, …)
• agent-bus-mcp — the MCP stdio server that Claude Code / Codex spawn

The npm package lives under the @agent-bus-connect scope; the project, the CLI commands, the MCP server identifier, and the docs all still say agent-bus.

Prefer building from source? git clone … && npm install && npm run build && npm link works too.

2. Register with Claude Code

claude mcp add -s user agent-bus -- agent-bus-mcp

3. Register with Codex CLI + Codex Desktop

Both read ~/.codex/config.toml. Grab the absolute paths:

readlink -f "$(which node)"            # copy this output
readlink -f "$(which agent-bus-mcp)"   # copy this output too

Then add the block (substitute the paths you just copied):

[mcp_servers.agent-bus]
command = "<paste node path here>"
args = ["<paste agent-bus-mcp path here>"]

Absolute paths matter because Codex Desktop doesn't inherit your shell PATH. After editing, Cmd+Q + reopen Codex Desktop fully.

4. (Recommended) Install the /main and /listen slash commands

Two one-line slash commands that make day-to-day use natural:

• /main <name> — primes a coordinator session to talk to the bus in plain English ("ask the reviewer to…", "delegate this…").
• /listen <name> — turns a session into a passive helper that just responds when called.

One-time install:

mkdir -p ~/.claude/commands
curl -fsSL https://raw.githubusercontent.com/MustaphaSteph/agent-bus/main/docs/commands/main.md   -o ~/.claude/commands/main.md
curl -fsSL https://raw.githubusercontent.com/MustaphaSteph/agent-bus/main/docs/commands/listen.md -o ~/.claude/commands/listen.md

5. Verify

agent-bus --version                # 0.4.0
claude mcp list | grep agent-bus   # ✓ Connected

Full install details + troubleshooting: docs/install.md.

Need a prompt to paste into Claude, Codex, or Cursor? See docs/agent-prompts.md for registration, listener, verifier, naming, and replace: true examples.

Try it

Open two new Claude Code sessions.

Terminal A — the helper. Type:

/listen helper-a

That session registers as helper-a and quietly waits for messages.

Terminal B — your main session. Type:

/main me

Then talk to it like a person:

Ask helper-a what 17 × 23 is.

Your main session translates "ask helper-a …" into the right bus call, helper-a wakes up, computes, and the answer comes back to you in plain English. No tool names. No JSON.

Terminal C (optional, you watching):

agent-bus watch

watch, log, whois, and tasks default to the current repo-derived project. Use --project all when you want the whole local bus.

/main and /listen each register their session once. After that the names live in ~/.agent-bus/bus.db and survive restarts. The coordinator phrases — "ask helper-a", "delegate this", "get a second opinion" — are translated by the slash command's playbook into the right ask / send / ask_best calls under the hood.

What you'll see

Within a couple of seconds:

Terminal C (the watcher) shows the live message flow:

agent-bus watch
  online  helper-a  [listening]
  online  me
---
14:52:01 #1 me → helper-a  ASK
  what is 17 × 23?
14:52:03 #2 helper-a → me  REPLY ↪#1
  391

Terminal A (helper-a) narrates briefly and goes back to listening:

listening as helper-a
← from me: "what is 17 × 23?"  → answered: "391"

Terminal B (your main session) prints the answer back in plain English:

helper-a says: 391.

From here, swap the math for "review my last commit", "run the test suite", "summarize this PR", "find every call to useAuth in the codebase", or anything else you'd want a peer session to handle. You stay conversational; the agent picks the right bus call.

What you get

• 20 MCP tools — direct messages, synchronous ask/reply, channels (fan-out), capability routing, conversation threads, at-least-once delivery with claim+ack, and first-class tasks with strict state machine.
• Cross-tool — Claude Code, Codex CLI, Codex Desktop, and any MCP-speaking agent share the same bus.
• Persistent — agents, messages, channels, threads, and tasks survive restarts via SQLite WAL.
• Project-scoped by default — MCP sessions derive a local project from cwd; global views are explicit with project: "*" or --project all.
• Zero infra — no daemon, no cloud, no auth. One file at ~/.agent-bus/bus.db.
• Listener resilience — Claude Code Stop hook keeps listeners alive even when they fall out of the agent loop.

Documentation

docs/install.md	Install for Claude Code, Codex CLI, Codex Desktop
docs/agent-prompts.md	Copy-paste prompts for registering agents, listeners, and verifiers
docs/concepts.md	Mental model: agents, messages, threads, channels, claims, tasks
docs/tools.md	All 20 MCP tools — signatures, errors, examples
docs/cli.md	agent-bus CLI reference
docs/patterns.md	Listener mode, async chat, capability routing, broadcast, ack/retry, threading
docs/architecture.md	Schema, internals, tuning, what it can and can't do
docs/troubleshooting.md	Common errors and fixes
docs/openapi.yaml	OpenAPI 3.1 spec — lint-clean, also rendered to docs/api-static.html
llms.txt	Single-file context to drop into an AI agent so it can use the bus
AGENTS.md	Codebase layout and rules for contributors editing src/

License

MIT.