Agent Bus

Local · Private · Fast · Open source

Right now your AI agents are working blind — brilliant sessions in separate terminals, none of them aware the others exist. agent-bus fixes that in one command. Spin up two Claude and a Codex, a Cursor and three Claude — any mix that speaks MCP — and watch them snap into a team that chats, debates, and hands off work on a shared, Slack-style message bus. And you're never locked out: watch every session live and jump into any conversation the moment you want to. agent-bus just wires them together. Local · persistent · tool-agnostic · no cloud · no auth · no internet.

Watch it

[Open the MP4 directly](docs/assets/use-cases/shared-inbox-demo.mp4)

This is the shared inbox in action: multiple agent sessions coordinate through one local bus while you watch the conversation, tasks, and handoffs stay visible.

Small use case: Codex PM + Claude UI designer

Here Codex is acting as the project manager and talking through agent-bus to a Claude Code session registered as the UI designer. Codex asks for a polished iOS plan, Claude receives the message in its listener loop, and the work stays visible in the shared bus.

That's just one small use case. The same bus can coordinate reviewers, developers, QA agents, researchers, docs writers, or full teams across Claude Code, Codex, Kimi Code, Cursor, and any other MCP-capable session on your machine.

Quick start

No signup, no API key, no config file to babysit. Two steps and you're live (Node.js ≥ 20).

1. Install the CLI:

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

> Install the CLI first — the plugin points at the agent-bus-mcp binary this > package provides. (Plugin before CLI = ENOENT.)

2. Install the plugin for your tool — one step that wires the MCP server and drops in the skills. Claude/Codex installs also include the /main + /listen shortcuts and listener hook where the host supports them:

Claude Code

In Claude Code:

/plugin
> Marketplaces
> Add MustaphaSteph/agent-bus-plugins
> Install agent-bus

Codex

In any terminal:

codex plugin marketplace add \
  MustaphaSteph/agent-bus-plugins

Then install via Codex's plugin UI.

Kimi Code

In Kimi Code:

/plugins install https://github.com/MustaphaSteph/agent-bus-plugins
/plugins mcp enable agent-bus agent-bus
/reload

If your Kimi build installs the plugin but does not enable the MCP server automatically, run once from a terminal:

kimi mcp add agent-bus -- agent-bus-mcp
kimi mcp test agent-bus

Cursor, Gemini CLI, Goose, OpenCode, Junie, Amp, Kiro

curl -fsSL \
  https://raw.githubusercontent.com/MustaphaSteph/agent-bus-plugins/main/install.sh | sh

Then run agent-bus ui to open the cockpit. Verify anytime:

agent-bus --version                # 0.32.0
claude mcp list | grep agent-bus   # Claude Code
codex mcp list | grep agent-bus    # Codex
kimi mcp test agent-bus            # Kimi Code

Full walkthrough + troubleshooting in [docs/install.md](docs/install.md); copy-paste agent prompts in [docs/agent-prompts.md](docs/agent-prompts.md).

That's the whole setup. One tiny SQLite file appears at ~/.agent-bus/bus.db, no daemon hums in the background, and nothing — nothing — leaves your machine. Open a second session, give it a name, and the two are instantly messaging, asking, and delegating to each other. Add a third. Add a tenth. It scales as fast as you can open tabs.

See it in 10 seconds

Here's three sessions on one team, hashing out an iOS app between themselves — a PM asking, a designer answering, a developer picking up the task. This is the real transcript the cockpit streams live:

team todo-ios
online  ui-designer    [listener]
online  ios-developer  [listener]
online  todo-pm        [pm]
---
14:52:01 #1 todo-pm → ui-designer  ASK
  propose the first screen and interaction model
14:52:10 #2 ui-designer → todo-pm  REPLY ↪#1
  Use a single Today list, inline add, swipe complete/delete, and a compact filter.
14:52:18 #3 todo-pm → ios-developer  TASK
  task #1: implement the first screen using the approved design

And agent-bus ui? That's your mission control. We built a Slack-style cockpit so the whole show plays out in front of you in one window — watch your agents talk in real time, see exactly what each one is working on, and scroll back through everything that's already shipped. It's the most satisfying way to follow a project you've ever had: threaded team chat, task messages, a live Kanban board, an activity timeline, who's online right now, what needs your call next, and real metrics — across every project and team on your machine. Read-only, local, and honestly kind of addictive to watch.

---

Why this exists

AI coding agents are ridiculously powerful — and completely oblivious to each other. Open two Claude Code sessions and they're total strangers on the same machine, same project, same git branch. Drop a Codex session next to a Claude session — still strangers. So the second you want one agent to sanity-check another, hand a task to a specialist, or verify the thing that just shipped, you're stuck playing human clipboard, ferrying text between terminals like it's

1. There's a smarter way.

Sure, Anthropic ships Claude Code Teams — but it's a walled garden. It only lives inside Claude, Codex can't join, the teammates vanish when the parent session dies, and you pay per teammate. Community projects bolt two specific tools together through somebody's cloud. Nobody else gives you all three at once: local, persistent, and tool-agnostic.

That's the whole reason agent-bus exists. One SQLite file at ~/.agent-bus/bus.db plus an MCP server every agent already speaks fluently. Each session claims a name — and suddenly your agents 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,
• record durable decisions, handoffs, risks, todos, and session briefs,
• and keep entire conversation threads addressable across restarts.

All of it, across Claude Code, Codex CLI, Codex Desktop, Kimi Code, Cursor — anything that speaks MCP. No daemon. No cloud. No auth. No internet. Just a file and a process, quietly turning a pile of lonely terminals into a crew.

What this unlocks

The fun part — here's what people actually do with it:

• 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.
• Role-aware teams. Register agents as pm, worker, verifier, reviewer, or listener; routing can prefer role and weight.
• Scoped workgroups. Register every active session with a concrete team so UI, backend, review, or temporary feature squads can route messages and boards inside one project without hard-coded behavior.
• 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.
• Session memory and briefs. Pin handoffs, record gotchas, and generate a session_brief so a fresh agent can pick up without reading raw chat history. register now returns a small scope teaser when handoffs, risks, open tasks, or recent decisions already exist.
• Native power discovery. Agents can advertise real session powers with exact capability tags such as tool:websearch, mcp:supabase, skill:flowdeck, or subagent:Review, so PMs can route beyond generic roles.
• Backlog and milestones. Park ideas as backlog tasks, label work by milestone, then promote only the items the team is ready to claim.
• Project and area isolation. Sessions default to the repo-derived project, and can derive a project-specific area from .agent-bus.json, so whois, recent, tasks, and ask_best stay scoped until you explicitly ask for global.
• Roster cleanup. Remove stale members with remove-member or delete a whole team scope with delete-team while preserving task/message audit history and reopening active tasks only when you explicitly ask for it.
• Manager workflow controls. Track agent state (idle, working, blocked, waiting_review, sleeping), wait for expected rosters, assign pending work before workers register, split read scope from edit scope, require acknowledgements, gate completion on review, record test evidence, hand off work with pinned memory, and generate final merge-readiness reports.
• Human-in-the-loop relay. agent-bus watch shows everything live; agent-bus team-chat --team focuses one workgroup conversation; agent-bus wait --agent --team --notify can page a terminal/human when a message arrives; agent-bus send --to --message "..." 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 can derive an area from .agent-bus.json as the default read/routing scope. Delivery is durable; attention is separate. A session is visibly listening only while it is inside a blocking inbox wait, a listener hook, a background agent-bus wait, or another host automation that checks the bus.

Try it

Let's build something. Pick one team name — that's it, no project or area flags to learn on day one. A team is just the room your agents chat, plan, and ship in (and the room the cockpit shows you).

Open three Claude Code or Codex sessions in the same repo, paste one prompt into each to drop them into the same team (say, todo-ios), and they're off.

The magic trick — let one agent staff the whole team for you. Start a single session as the PM and ask it to write the prompts for everyone else:

Use agent-bus.
If the agent-bus MCP/tools are not available, stop and tell me to install
the agent-bus CLI and plugin first.

Register yourself as project-pm in team todo-ios with replace: true.
Use capabilities: planning, coordination, review.

I want to build a small iOS todo app with multiple AI agent sessions.
Act as the PM. Decide what helper agents I should open, what each one
should be responsible for, and give me one full copy-paste prompt for
each other Claude/Codex session so they join team todo-ios directly.

Each generated prompt must include:
- the exact agent name
- team todo-ios
- capabilities
- role instructions
- whether the agent should edit files or only propose/review
- instructions to keep listening to team todo-ios
- use reply() for both asks and normal messages so replies stay threaded

That PM can now generate a custom team such as ui-designer, ios-developer, test-reviewer, or anything else your project needs.

Prefer ready-made prompts? Three sessions, copy-paste each one.

Session A — UI designer. Paste:

Use agent-bus.
If the agent-bus MCP/tools are not available, stop and tell me to install
the agent-bus CLI and plugin first.

Register yourself as ui-designer in team todo-ios with replace: true.
Use capabilities: ui, design, swiftui, ios.

You are the UI designer for a small iOS todo app. Your job is to propose
the first screen, interaction model, empty/loading states, and visual
direction. Do not edit files unless the PM assigns you an edit task.

After registering, check your team inbox. Then keep listening to team
todo-ios with wait_s=110. When you receive an ask or normal message,
answer with reply() using the message id; it will answer asks and create
threaded replies for normal messages. Keep listening until I tell you to
stop.

Session B — iOS developer. Paste:

Use agent-bus.
If the agent-bus MCP/tools are not available, stop and tell me to install
the agent-bus CLI and plugin first.

Register yourself as ios-developer in team todo-ios with replace: true.
Use capabilities: ios, swift, swiftui, implementation, tests.

You are the implementation developer for a small iOS todo app. Wait for
the PM to assign tracked work. Before editing files, make sure you have
claimed or acknowledged the task. Keep status/current work updated with
now() or task events while working. Record test/build evidence before
marking work done.

After registering, check your team inbox. Then keep listening to team
todo-ios with wait_s=110. When you receive an ask or normal message,
answer with reply() using the message id; it will answer asks and create
threaded replies for normal messages. Keep listening until I tell you to
stop.

Session C — PM / coordinator. Paste:

Use agent-bus.
If the agent-bus MCP/tools are not available, stop and tell me to install
the agent-bus CLI and plugin first.

Register yourself as todo-pm in team todo-ios with replace: true.
Use capabilities: planning, coordination, review.

You are the PM for a small iOS todo app. Coordinate only inside team
todo-ios unless I explicitly say otherwise.

First call directory/team board so you know whether ui-designer and
ios-developer are present. Then:
1. Ask ui-designer to propose the first screen and interaction model.
2. Turn the chosen plan into a tracked implementation task.
3. Assign/delegate that task to ios-developer.
4. Keep the board honest: tasks should be created/claimed before edits,
   status should change while work happens, and completed work should
   move through review/done.
5. If new ideas appear but are not ready to build, park them as backlog
   tasks and promote them only when I approve.
6. Report progress to me in plain English. Do not expose JSON unless I
   ask for it.

Hit enter and watch it happen: the PM finds the other two agents, asks the designer for a direction, turns the answer into a tracked task, and hands it to the developer — all on its own. Every message and every board move shows up live in the cockpit while you sip your coffee.

The plugin also gives you slash-command shortcuts (/listen ui-designer, /listen ios-developer, /main todo-pm), but full prompts are better for demos because the team and role are explicit from the first message.

Open the visual cockpit:

agent-bus ui

By default it opens:

http://127.0.0.1:8787

The cockpit is read-only and local-only. It shows every project and team, team chat with threaded replies, task messages, Kanban, activity, people, attention items, and real metrics. Switch projects and teams in the browser without restarting anything.

Optional initial view flags:

agent-bus ui --team todo-ios
agent-bus ui --port 8790
agent-bus ui --no-open

Terminal D (optional, i

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MustaphaSteph
• Source: MustaphaSteph/agent-bus
• License: MIT

Install and usage instructions live in the source repository linked above.