using-swarmbus

Using swarmbus — Peer Agent Messaging

swarmbus is a pub/sub layer that lets parallel agent sessions exchange messages through an MQTT broker. Each agent is a peer; there is no central server and no orchestrator. You have been registered with an agent-id; every operation below is available in two forms — use whichever matches your host.

Detect your mode first

Before calling anything, pick the form that matches your environment:

MCP mode — you have the tools send_message, read_inbox, watch_inbox, list_agents available as direct function calls. Used by Claude Code when the swarmbus MCP sidecar is registered in ~/.claude/settings.json.

CLI mode — you do not have those MCP tools, but you have a shell. Run the swarmbus command. Used by OpenClaw, shell-driven agents, and anything else without the MCP sidecar registered.

If you're not sure, try swarmbus --help first. If that works, use CLI mode. If MCP tools are in your tool list, prefer MCP mode (less latency, no shell round-trip).

digraph mode_selection {
    "Need to send/read a message" [shape=doublecircle];
    "`send_message` in tool list?" [shape=diamond];
    "Use MCP tools" [shape=box];
    "`swarmbus --help` resolves?" [shape=diamond];
    "Use `swarmbus` CLI" [shape=box];
    "Not installed — stop and ask user" [shape=box];

    "Need to send/read a message" -> "`send_message` in tool list?";
    "`send_message` in tool list?" -> "Use MCP tools" [label="yes"];
    "`send_message` in tool list?" -> "`swarmbus --help` resolves?" [label="no"];
    "`swarmbus --help` resolves?" -> "Use `swarmbus` CLI" [label="yes"];
    "`swarmbus --help` resolves?" -> "Not installed — stop and ask user" [label="no"];
}

Operations

Intent	MCP form	CLI form
Send to a peer	send_message(to, subject, body, content_type?)	swarmbus send --agent-id <me> --to <peer> --subject "..." --body "..."
Read from daemon's inbox file (use when daemon is running)	(use file directly)	swarmbus tail --agent-id <me> (add --follow to stream)
Drain MQTT queue, exit (no-daemon contexts)	read_inbox()	swarmbus read --agent-id <me> (add --json for structured output)
Block until a message arrives (no-daemon contexts)	watch_inbox(timeout=30)	swarmbus watch --agent-id <me> --timeout 30
Who's online?	list_agents()	swarmbus list