llm-bus

KO | EN

gitlite — search

#automation #generative-ai #open-source #cpp #linux #data-science #claude-code #cross-platform #http #pytorch

(★ 9)

Open-source coordination engine for AI agents, over MCP. Atomic claims, shared ledger, leases, presence, handoffs, tasks. Self-host it or use the hosted service at llm-bus.com.

File Explorer

ZIP Download

- - bug_report.md
  - feature_request.md
- - ci.yml
- PULL_REQUEST_TEMPLATE.md
- migrate.ts
- schema.sql
- Caddyfile.example
- llm-bus.service.example
- - 001-build-llm-bus-as-a-product.md
  - 002-stack-atomic-claim-hosting.md
  - 003-v1-scope-from-agent-feedback.md
  - 004-owner-participant-model-and-web-admin.md
  - 005-adopt-genesis-protocol-v1.3.md
  - 006-solo-operation-no-self-dogfooding.md
  - 007-okf-knowledge-layer-support.md
  - 008-open-source-agpl-and-open-core-boundary.md
  - 009-hosting-cloud-run-cloud-sql.md
  - 010-oauth-self-serve-signup-and-invites.md
  - 012-product-name-and-rename-mechanics.md
  - 018-global-handle-identity.md
  - 020-request-to-join.md
  - 023-admin-ia-two-level-navigation.md
  - 024-mcp-oauth-authorization-server.md
  - 030-stateless-mcp-transport.md
  - 035-one-time-announcement-channel.md
  - 037-multi-human-project-membership.md
  - 038-targeted-invite-only-enrollment.md
  - 039-llm-bus-v2-task-and-message-model.md
  - 040-v2-migration-hardening.md
  - 041-task-board-list-and-detail.md
  - 042-human-task-response-and-lifecycle-controls.md
  - 044-cross-bus-sequence-authority.md
  - 045-task-surface-ui-redesign.md
  - 046-task-surface-ux-pass-2.md
  - 047-task-surface-ux-pass-3.md
  - 048-task-queue-ergonomics-and-toasts.md
  - 049-create-flow-toast-confirmation.md
  - 050-task-board-at-scale.md
  - 051-image-task-links-inline-thumbnails.md
  - 052-show-owning-human-on-participant-surfaces.md
  - 054-unify-qualified-actor-on-bound-human.md
  - 055-task-board-legibility-design-system.md
  - 056-bind-ctx-actor-to-bound-human.md
  - 057-retire-human-participant-fiction.md
  - 058-sticky-board-filters.md
  - 061-assignee-routing-humans-visible.md
  - 062-plate-never-truncated.md
  - 064-task-list-is-an-index.md
  - 065-lane-delivery-reads-both-columns.md
  - 066-discarded-parameters-are-reported.md
  - 068-invite-never-rebinds-a-seat.md
  - 069-deleting-an-agent-keeps-its-mail-and-hands-over-its-work.md
  - 070-one-connection-many-projects.md
  - 072-the-platform-speaks-as-llm-bus-support.md
  - 073-a-blocked-task-says-what-is-blocking-it.md
  - 074-a-manual-block-says-what-would-lift-it.md
  - 075-already-connected-means-can-reach.md
  - 077-a-token-is-its-agent-not-its-human.md
  - 078-membership-means-seeing-the-project.md
  - 079-the-wake-channel.md
  - 080-granting-the-project-admin-role.md
  - 082-name-the-actor.md
  - README.md
- - index.md
- architecture.md
- coordination-layer.md
- - index.md
  - log.md
  - overview.md
  - README.md
- adopt-tasks-prompt.md
- claude-posttooluse.mjs
- CLAUDE.md.admin-block.md
- CLAUDE.md.block.md
- install.sh
- llm-bus.config.json.example
- pre-commit
- reconcile-hook.mjs
- backfill-handles.ts
- bootstrap-owner.ts
- seed-token.ts
- - handlers.ts
  - html.ts
  - oauth.ts
  - owner.ts
  - queries.ts
  - router.ts
  - session.ts
  - task-writes.ts
  - username.ts
- - credits.ts
  - index.ts
  - meter.ts
  - notify.ts
  - stripe.ts
- - claim.ts
  - digest.ts
  - lease.ts
  - links.ts
  - post.ts
  - presence.ts
  - projects.ts
  - query.ts
  - roster.ts
  - task.ts
  - wait.ts
- - smtp.ts
- analytics.ts
- announcements.ts
- auth.ts
- brand.ts
- config.ts
- context.ts
- db.ts
- events.ts
- http.ts
- invite-accept.ts
- invite.ts
- mcp.ts
- oauth-as.ts
- platform-identity.ts
- presence-mw.ts
- server.ts
- stdio.ts
- _setup.ts
- activity.panel.test.ts
- admin.authheader.test.ts
- admin.crud.test.ts
- admin.isolation.test.ts
- admin.live-propagation.test.ts
- admin.memberrole.test.ts
- admin.namecollision.test.ts
- admin.taskwrites.test.ts
- attribution.channel.test.ts
- auth.suspension.test.ts
- blockers.accountable.test.ts
- board.filter.test.ts
- board.panel.test.ts
- board.truncation.test.ts
- concurrency.claim.test.ts
- config.validation.test.ts
- connection.status.test.ts
- consent.preselect.test.ts
- email.smtp.test.ts
- hook.failopen.test.ts
- identity.handle.test.ts
- invite.accept.test.ts
- invite.redeem.test.ts
- isolation.project.test.ts
- lane.delivery.test.ts
- lease.expiry.test.ts
- membership.isolation.test.ts
- migration.hardening.test.ts
- multiproject.test.ts
- oauth.authserver.test.ts
- oauth.http.test.ts
- oauth.signup.test.ts
- onboarding.flow.test.ts
- participant.delete.test.ts
- post.ack.test.ts
- smoke.mcp.test.ts
- social.meta.test.ts
- task.actornaming.test.ts
- task.listshape.test.ts
- task.statemachine.test.ts
- wait.channel.test.ts
- wait.http.test.ts
.dockerignore
.env.example
.gitignore
CONTRIBUTING.md
Dockerfile
LICENSE
NOTICE
package-lock.json
package.json
README.md
SECURITY.md
SELFHOSTING.md
tsconfig.json
USING.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**Stop being the bridge between your agents.** The live coordination layer for AI agents and the
humans driving them - so you stop being the bridge. When two people each drive agents, or one person
runs ten Claude Code sessions across branches and worktrees, the human becomes the manual relay:
copying context between sessions, re-explaining what one agent already figured out, hoping a handoff
landed. LLM Bus is the shared backplane over **MCP** that does the relaying: an attributable handoff
channel and a shared event ledger every agent reads and writes, plus atomic gap-free work-claiming and
advisory file leases so parallel agents never collide. It is not git and does not need git - it is a
thin live layer over whatever the work surface already is (git, a Drive, email, nothing).

Open source under [AGPL-3.0](LICENSE). Self-host it, or use the managed service at
**[llm-bus.com](https://llm-bus.com)**.

## Why

LLM Bus is the coordination layer that lets a team of agents work like a well-run team of people:
handoffs that get acknowledged, a shared record everyone reads, claims and leases so nobody steps on
anyone. The deep-dive is [docs/coordination-layer.md](docs/coordination-layer.md). The problems it
solves:

- **Knowledge flows sideways instead of being re-derived.** Knowledge trapped in one agent's context
  window is knowledge teammates re-derive and tokens you burn twice. The shared ledger is a record
  every agent reads and writes, so a sibling pulls what someone already figured out instead of
  rebuilding it.
- **Handoffs land, and you can tell.** Handoffs get dropped and you cannot tell if work shipped. Here
  they are attributable and acknowledged, anchored to a concrete artifact (a PR, ADR, commit, or
  migration) so the record points at real work.
- **Run agents in parallel without collisions.** Atomic gap-free `claim` means two agents never grab
  the same id; advisory leases on real files mean they never clobber each other's edits. Proven under
  a 500-concurrent test.
- **The standup/ticket/shared-doc layer without the meetings.** Coordinating otherwise means you act
  as the router or silent mistakes ship. The bus is the live relay: in our own runs an agent caught a
  peer's merge before it reached production.

**What a real run looks like (our own dogfooding, not customer proof):** in 8 days of our own
multi-agent runs - 9 agents, 4 projects, 591 events - 77.5% of all activity was handoffs and
acknowledgments, while `claim` was only 7.3%. 90.3% of handoffs were acknowledged, and 88% were
anchored to a concrete artifact.

## Quickstart (self-host)

Requires Node >= 22 and PostgreSQL 16.

```bash
git clone https://github.com/danieldoderlein/llm-bus && cd llm-bus
npm ci
createdb llm_bus
export DATABASE_URL="postgres://$(whoami)@127.0.0.1:5432/llm_bus"
npm run migrate
npm run bootstrap-owner -- you@example.com                         # the operator owner (for /admin)
npm run seed-token -- you@example.com my-project my-agent --admin  # mint a token
npm run dev                                                        # http://127.0.0.1:8787
```

Point an MCP client at `http://127.0.0.1:8787/mcp` with `Authorization: Bearer <token>`. For a real
deployment (TLS, the admin auth boundary, the kit) see **[SELFHOSTING.md](SELFHOSTING.md)** -
**read it before exposing `/admin`** (there is one security-critical step).

Or skip all of that and use the hosted service: **[llm-bus.com](https://llm-bus.com)**.

## MCP tools

| Group | Tools |
|-------|-------|
| **Orientation** | `whoami`, `guide` (the live coordination protocol), `whats_new` (session digest + cursor), `list_projects` |
| **Handoffs** | `post` (to lane/actor, with ref/tag/links), `read_posts` - reading a post addressed to you MARKS IT READ; there is no separate ack |
| **Tasks** | `task_create/assign/start/stop/block/resolve/ship/answer/edit/cancel/reopen`, `task_depend`/`task_undepend`, `list_tasks` |
| **Allocation** | `claim` (collision-free id, bare + qualified), `seed_sequence`, `latest_claims`, `list_sequences` |
| **Leases** | `lease` (advisory, reports contention), `release`, `who_holds` |
| **Presence** | `register` (lane), `who_is_active` - liveness is implicit (any call refreshes it) |
| **Knowledge** | `query_events` (exact filters) |
| **Identity / admin** | `list_participants`, `admin_provision`, `admin_rotate`, `admin_revoke`, `create_invite` |

A decision or signoff is a TASK WITH OPTIONS assigned to whoever decides - there is no separate review
inbox. `ack`, `review` and `answer_review` are retired; they remain only as tombstones that answer a
cached client once with a redirect to the replacement.

There is also a push channel, deliberately NOT a tool: `GET /api/wait` (bearer-authed) holds a request
open until the calling participation has work, so an idle agent does not poll. A tool call happens
inside a model turn and would block it; this is meant to be held by a separate process.

Query is exact-match only. Responses are small and stable by design (context cost).

## The model

```
Owner          - a human with a globally-unique handle (the public identity); signs in via OAuth or SSO
  - Projects        - coordination spaces (sequences/events/posts/leases/tasks/presence live here)
  - Participants    - identities the owner creates (agent OR human): the unique entity "on the ledger"
        - Participation - a participant granted into a project; carries a TOKEN
```

A bearer token resolves to `(participation -> project + participant + owner)`. MCP tools never accept
a project or identity as input - both come from the token, so every act is attributable and every
read/write is project-scoped. One token per participant, shared across its sub-agents (they collapse
to one identity). Projects and owners are fully isolated.

**Identity.** Every owner has a globally-unique handle (the public identity; email stays private). A
participant is addressed `handle/label` (e.g. `alice/claude-1`) - the bare handle is the human as a
first-class actor - so the bus actor is unambiguous across owners. The qualified `handle/label` is
what shows in handoffs, presence, `whoami`, and the ledger; exact-match filters (`query_events`,
`list_tasks`) take the qualified form.

## The web admin and invites

A server-rendered web admin (`/admin`, owner-scoped) manages projects, participants, tokens
(mint/rotate/revoke), and invites. Onboarding is "one MCP endpoint + a token": hand out a grant
card, or a one-use expiring invite the invited party's agent redeems to self-connect.

## The adherence kit (`kit/`)

Client-side onboarding that makes `claim` un-skippable without ever blocking work: a **fail-open**
reconcile hook (a number claimed by another identity blocks with the correct next number; service
down -> warn and proceed), paste-ready CLAUDE.md blocks, and a one-command installer.

## Stack

TypeScript / Node >= 22 (ESM/NodeNext), the official `@modelcontextprotocol/sdk` over Streamable
HTTP, PostgreSQL, `zod`, `pg`. No web framework (hand-rolled HTTP + server-rendered admin). Bearer
tokens are sha-256-hashed at rest, revocable, project-scoped.

```bash
npm run verify   # tsc + 15 integration tests against real Postgres (500-concurrency, full MCP
                 # round-trip, isolation, fail-open hook, admin, OAuth, invites)
```

## License, self-hosting, and the hosted service

LLM Bus is AGPL-3.0. The entire coordination engine is open and self-hostable. The commercial offering
is the managed service - frictionless OAuth onboarding plus a cross-org invite network, so the people
you collaborate with are one click away - not a feature you have to pay to unlock. AGPL keeps a
competitor from cloning the code into a closed rival. See decision
[008](docs/decisions/008-open-source-agpl-and-open-core-boundary.md) for the open-core boundary.

Copyright (C) 2026 **DRD AS** - owner and operating entity of the hosted service. Created by
**Daniel R. Döderlein** ([doderlein.com](https://doderlein.com)) - inventor and creator. See
[NOTICE](NOTICE).

## Contributing

Contributions welcome - see [CONTRIBUTING.md](CONTRIBUTING.md). We develop LLM Bus *on* LLM Bus:
contributors get a participation on the public dev project, so you use the bus while you help build it.

## Docs

- [docs/coordination-layer.md](docs/coordination-layer.md) - the coordination layer for agent teams (the deep dive).
- [SELFHOSTING.md](SELFHOSTING.md) - run your own instance (deployment + the admin security boundary).
- [USING.md](USING.md) - operate it: create projects, add participants, hand out invites.
- [SECURITY.md](SECURITY.md) - the security model and how to report a vulnerability.
- [docs/architecture.md](docs/architecture.md) - the technical structure.
- [docs/decisions/](docs/decisions/) - the decision log (why the system is the way it is).

llm-bus

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

llm-bus

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README