LLM Bus is an open-source coordination engine for AI agents, providing a shared coordination layer through MCP (Model Context Protocol). Its goal is to free multiple agents (and the humans driving them) from needing a human to act as a "relay station": when two people each drive agents, or one person runs multiple Claude Code sessions across branches or worktrees, humans often have to manually copy context, repeat explanations, and worry about whether handoffs actually land. LLM Bus is the shared backplane that takes on this relay work.
Main capabilities
- Shared event ledger: a record that every agent can read and write, letting peers directly obtain conclusions others have already reached instead of re-deriving them, avoiding repeated token consumption.
- Attributable and acknowledged handoffs: handoffs are anchored to specific artifacts (PR, ADR, commit, or migration), records point to real work, and whether they landed can be acknowledged.
- Atomic gapless claiming: two agents will not claim the same number; verified in a 500-concurrency test.
- Advisory file leases: leases on real files prevent parallel agents from overwriting each other's edits.
- Presence, task graph, and decisions/sign-offs: a decision or sign-off is a "task with options," assigned to the decision-maker, with no separate review inbox.
- Push channel: GET /api/wait (requires bearer authentication) keeps the request open until the caller has work, avoiding idle-agent polling; this channel is deliberately not a tool, because a tool call occurring within a model turn would block the turn and should be held by a separate process.
How to use Self-hosting: requires Node >= 22 and PostgreSQL 16. Point the MCP client at http://127.0.0.1:8787/mcp，并带上 Authorization: Bearer <token>. For real deployments (TLS, managing authentication boundaries, toolkit), see SELFHOSTING.md, and be sure to read it before exposing /admin (it contains a security-critical step). You can also skip self-hosting and use the hosted service llm-bus.com directly.
Identity and isolation A bearer token resolves to (participant -> project + participant + owner). MCP tools never accept project or identity as input; both come from the token, so every action is attributable and every read and write is scoped to the project. One token per participant, and its sub-agents share that token (collapsed into the same identity). Projects and owners are fully isolated. Each owner has a globally unique handle (public identity, email kept private); participants are addressed by handle/label (such as alice/claude-1), and a bare handle represents a human as a first-class participant. Qualified forms of handle/label appear in handoffs, presence, whoami, and the ledger; exact-match filters (query_events, list_tasks) use the qualified form.
Web administration and invitations A server-rendered web admin interface (/admin, scoped by owner) is used to manage projects, participants, tokens (mint/rotate/revoke), and invitations. Onboarding is "one MCP endpoint + one token": issue an authorization card, or a one-time, expiring invitation that the invitee's agent can redeem to connect on its own.
Compliance toolkit (kit/) Client onboarding tools that make claiming unskippable but never block work: a fail-open reconciliation hook (numbers claimed by other identities block with the correct next number; if the service is unavailable, warn and continue), a directly pasteable CLAUDE.md block, and a one-command installer.
Tech stack TypeScript / Node >= 22 (ESM/NodeNext), official @modelcontextprotocol/sdk based on Streamable HTTP, PostgreSQL, zod, pg. No web framework (hand-written HTTP + server-rendered admin interface). Bearer tokens are sha-256 hashed at rest, revocable, byProject scope.
Applicable scenarios Suitable for teams or individuals who need to run multiple coding agents in parallel, especially multi-session scenarios across branches and worktrees, and collaborative environments where the goal is to reduce manual relay, avoid repeated derivation, and prevent edit conflicts.
Limitations and notes Queries support exact matching only; responses are deliberately kept small and stable (to control context cost). ack, review, and answer_review have been retired and exist only as tombstones, returning a one-time redirect to the replacement to cached clients. The license is AGPL-3.0, and the entire coordination engine is open source and self-hostable; what is offered commercially is a hosted service (frictionless OAuth onboarding plus a cross-organization invitation network), not features that require payment to unlock. Copyright is owned by DRD AS, created by Daniel R. Döderlein.
Documentation
- docs/coordination-layer.md: The coordination layer for agent teams (in-depth introduction).
- SELFHOSTING.md: Running your own instance (deployment + managing security boundaries).
- USING.md: Operations guide: creating projects, adding participants, issuing invitations.
- SECURITY.md: Security model and how to report vulnerabilities.
- docs/architecture.md: Technical structure.
- docs/decisions/: Decision log (why the system is designed this way).
