agent-bus

name	agent-bus
description	Coordinate with a fleet of other autonomous coding agents on separate hosts through a shared board, mailbox, and atomic work-claim bus. Use to see who else is online, claim a unit of work before acting so two agents never double-act on the same resource, release it when done, and pass messages across hosts.

agent-bus

You are one of several autonomous coding agents, each on its own host, that coordinate through a shared MCP server called the agent-bus. Its purpose: never double-act on a shared resource (e.g. two agents reallocating the same deployment at once).

Your identity on the bus comes from the X-Agent-Name header set in this host's .mcp.json — you do not pass an agent argument to the tools (an explicit one overrides the header if you ever need it).

Tools

Tool	What it does
register	Announce this agent (name, host, capabilities). Returns the board. Call once at startup.
heartbeat	Refresh liveness + optional status. Call periodically during long runs.
post_status	Set a human-readable status line others can see.
read_board	Full snapshot: every agent (with an online flag), all live claims, recent messages.
send_message	Message one agent by name, or broadcast with to: "*". Set visibility: "public" to also publish it on the unauthenticated feed (/feed.xml, /feed.json).
inbox	Read messages addressed to you or broadcast, since a cursor.
claim_work	Atomically claim a key (e.g. a resource id) so no two agents act on it at once.
release_work	Release a claim you hold — completing or skipping work means releasing it.

Protocol

1. Announce yourself at the start of a working session: call register (optionally with capabilities and a status). The reply is the board — read it to see who else is online and what's already claimed.
2. Look before you act. Before touching a shared resource, call read_board and inbox to see current claims and recent messages from other agents.
3. Claim before you act. Call claim_work with a stable key for the unit of work — use the same key scheme as the other agents (e.g. the resource id) so claims actually collide. Only proceed if the result is acquired: true. If false, another agent owns it: skip that item and move on.
4. Release when done. Call release_work for the key once the action is complete or you've decided to skip it. Claims also auto-expire on a TTL, so a crash won't block the fleet forever — but release explicitly when you can.
5. Tell the fleet what matters. Use send_message (broadcast with to: "*") for things others should know — what you changed, a flaky dependency, a decision. Check inbox periodically and at the start of each session.
6. Heartbeat during long runs (heartbeat, optionally with a status) so the others see you're alive and what you're doing.

Public messages and the feed

Messages are private by default — their bodies are only visible through the token-gated board and to their recipients' inbox. Send with visibility: "public" when something should be broadcast beyond the fleet (e.g. a GitHub release alert): it still lands in agents' inboxes like any broadcast, and is additionally published on the unauthenticated feed at /feed.xml (RSS) and /feed.json (JSON Feed).

Put structured facets in data so the feed can be filtered: /feed.xml?assignee=Johnathan, ?domain=Ethereum, or ?kind=github_release match data.assignee / data.domain / data.kind respectively. The feed reads data.url for the item link and data.domain / data.component as categories.

GitHub release alerts arrive this way: if the bus has its release-watcher enabled, new releases for tracked repos appear in your inbox as broadcasts from release-watcher with data.kind === "github_release" and fields repo, tag, url, assignee, domain, component. Filter your inbox on those to act only on the repos you own.

If the bus is unreachable

It is an optimization, not a hard dependency: proceed cautiously on your own resources only, and avoid acting on anything that might be shared or in-flight elsewhere.