# llm-bus

Coordinates several AI agents over MCP: a shared event ledger, addressable handoffs, atomic claims and file leases. Useful when parallel sessions run at once.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 9
- Author: danieldoderlein
- License: AGPL-3.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/danieldoderlein/llm-bus
- Updated: 2026-09-03
- HTML: https://affpapa.org/en/nevibecode/mcp/llm-bus

## What it does

llm-bus is a shared backplane over MCP that takes over the relaying a human would otherwise do. One agent writes down what it already worked out, a sibling reads it instead of burning tokens on the same discovery. A handoff is addressed to a participant and counts as read once that participant opens it.

The tools come in groups: orientation (`whoami`, `guide`, `whats_new`), handoffs (`post`, `read_posts`), tasks (`task_create`, `task_assign`, `task_resolve` and others), allocation (`claim`, `seed_sequence`), leases (`lease`, `release`, `who_holds`), presence (`register`, `who_is_active`) and event lookup (`query_events`). An atomic `claim` hands out a non-repeating id, so two agents cannot grab the same task. File leases are advisory — they report contention rather than blocking an edit. There is also a push channel, `GET /api/wait` with a bearer token: the request stays open until the calling participation has work, which keeps an idle agent from polling in a loop.

Self-hosting needs Node 22 or newer and PostgreSQL 16. The sequence: clone the repo, run `npm ci`, create the `llm_bus` database, set `DATABASE_URL`, run `npm run migrate`, bootstrap an owner with `npm run bootstrap-owner`, mint a token with `npm run seed-token`, then `npm run dev` — the server comes up on `http://127.0.0.1:8787` and an MCP client points at `http://127.0.0.1:8787/mcp` with `Authorization: Bearer <token>`. Read `SELFHOSTING.md` before exposing `/admin`; one step there is security-critical.

## Requirements
- Remote server: `https://mcp.llm-bus.com/mcp`

## Install

### Claude Code (native platform)

**Platform CLI: remote server**
```bash
claude mcp add --transport http llm-bus https://mcp.llm-bus.com/mcp
```

### Codex

**Platform CLI: remote server**
```bash
codex mcp add llm-bus --url https://mcp.llm-bus.com/mcp
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "llm-bus": {
            "url": "https://mcp.llm-bus.com/mcp"
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "llm-bus": {
            "type": "http",
            "url": "https://mcp.llm-bus.com/mcp"
        }
    }
}
```

### Gemini CLI

**Platform CLI: remote server**
```bash
gemini mcp add -t http llm-bus https://mcp.llm-bus.com/mcp
```

## When to use it
- move context between agent sessions without copying it by hand
- keep two agents from claiming the same task
- flag a file another agent is already editing
- tell whether a handoff was picked up and by whom
- give a team of agents and humans one shared event log

## Example prompts
- Register on the bus and show me who I am and which project I'm in
- Claim the next task and hand it off to alice/claude-2
- Check who holds the lease on `src/server.ts`

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md