Skip to main content
Glama

agent-bus

中文

A shared blackboard for AI coding agents that run on the same machine. Claude Code, Codex, or any other MCP client connect to it and can then:

  • claim a topic before acting on it, so two agents never send the same email or open the same PR;

  • hand off a task to another agent and track it to done or failed;

  • post a one-line status the other agents and you can read.

It is one Node file with no dependencies. State is one JSON file you can open and read.

dashboard

Why

Two agents working for the same person cannot see each other's sessions. Give both the same request and they both do it. This started after two agents each drafted a reply to the same email. The fix is small: before any outward action, take a lock that the other agent can see.

Related MCP server: Pursers

Install

Needs Node 18 or later.

git clone https://github.com/SLYysl/agent-bus.git
cd agent-bus
node test.js          # should end with ALL TESTS PASS

Connect each agent to the same server.js. Use the absolute path.

Claude Code

claude mcp add --scope user agent-bus -- node /absolute/path/to/agent-bus/server.js

Codex — add to ~/.codex/config.toml:

[mcp_servers.agent-bus]
command = "node"
args = ["/absolute/path/to/agent-bus/server.js"]

Any other MCP client: run node server.js over stdio.

All agents must point at the same board file. By default that is board.json next to server.js; set AGENT_BUS_FILE to put it elsewhere.

Then give the agents the rules:

  • copy AGENTS.md into each agent's instruction file and edit the names, or

  • for Claude Code, copy skills/agent-bus into ~/.claude/skills/.

Try it

In one agent:

Use agent-bus: claim the topic demo:hello as claude.

In the other:

Use agent-bus: claim the topic demo:hello as codex.

The second one is told ALREADY CLAIMED … by claude and stops.

Tools

Tool

What it does

claim(topic, by, note?)

Lock a topic. Returns claimed or ALREADY CLAIMED with the holder.

release(topic, by, result?)

Mark the topic done with a one-line result.

handoff(to, task, by, note?)

Create a task for another agent. Returns a task id.

inbox(agent)

List open tasks handed to that agent.

ack(taskId, by)

Take a task: new → picked.

complete(taskId, by, result?) / fail(taskId, by, reason?)

Close a task.

post(key, value, by) / get(key)

Write and read a status value.

board()

Everything: values, active claims, open and recently closed tasks, recent activity.

Agent names are free text. Use the same spelling every time.

Dashboard and watcher

node dashboard.js     # http://127.0.0.1:4317, read-only
node watcher.js       # dry-run: prints which agent it would wake
node watcher.js --go  # actually runs `codex exec …` / `claude -p …` for new tasks

The dashboard shows each agent's last activity, active claims and the task lanes, and tells you which agent to nudge. The watcher is off by default because --go starts agent runs that spend tokens. Edit TRIGGERS in watcher.js to change the commands.

Limits

  • Agents do not wake up by themselves. MCP is pull-based. Without the watcher, a handed-off task waits until you tell the receiver to check its inbox.

  • One machine. The board is a local file. Two machines have two separate boards.

  • Trust. Any process that can write the file can write the board, and by is not verified. This coordinates cooperating agents; it is not access control.

  • Claims expire after 30 minutes, so a crashed agent cannot hold a topic forever. A task that takes longer should be re-claimed.

  • The board holds what agents write to it. Keep entries short and keep secrets out. board.json is git-ignored for that reason.

How the lock works

Every agent's MCP client starts its own server.js process, so several processes write one file. Each mutating tool takes an exclusive lock file (board.json.lock, created with O_EXCL), reads, changes, writes to a temp file and renames it over the board. test.js starts 12 processes that race for 25 topics and checks that each topic gets exactly one winner; with the lock removed the same test reports over 200 winners.

License

Apache-2.0

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables multiple AI coding agents to coordinate on a shared software project by registering, claiming tasks, declaring file intents, publishing structured change reports, and handing off context, with a local dashboard showing state in near real time.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Local OS for your AI Agents fleets. ——————- Enables AI agents to coordinate through a durable local board with shared state, ticket lifecycle, evidence-based approvals, and journal-woken handoffs.
      3
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables multiple AI agents and humans working in the same project to share status, exchange messages, and claim files through a local collaboration board. It supports project-specific enablement, conflict-aware file claims, and shared state via SQLite.
      7
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables multiple AI coding agents and humans to coordinate through a Git-native Markdown blackboard (.context/ + AGENTS.md), where they can inspect workspace overviews, claim and toggle ready tasks, record architecture decisions, synthesize shared prompts, and hand off work via atomic, lock-protected writes that prevent lost updates and formatting drift. It also serves a fully offline local web dashboard that live-syncs any blackboard change over WebSocket.
      7
      1
      MIT