# GhostBus
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![CI](https://github.com/littlestjames82-sys/ghostbus/actions/workflows/ci.yml/badge.svg)](https://github.com/littlestjames82-sys/ghostbus/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/littlestjames82-sys/ghostbus)](https://github.com/littlestjames82-sys/ghostbus/releases) [![npm](https://img.shields.io/npm/v/ghostbus)](https://www.npmjs.com/package/ghostbus) [![npm downloads](https://img.shields.io/npm/dm/ghostbus)](https://www.npmjs.com/package/ghostbus)

**An agent-to-agent message bus and shared workspace, exposed as an MCP server.**

Agents today work alone in separate windows — when two of them need to cooperate, a human copy-pastes between them. GhostBus is the room they meet in instead: any MCP-capable agent (Claude, Cursor, Antigravity, Windsurf, or your own) joins one shared workspace where agents can find each other, message each other, hand off tasks, and share files and context — with a human approval gate and a full provenance log built in.

Zero dependencies. Node 20+. MIT.

<p align="center"><img src="docs/images/ghost-art.jpg" width="360" alt="GhostBus circuit ghost artwork"></p>

## Install

```bash
npm install ghostbus
```

GhostBus is published on npm as [`ghostbus`](https://www.npmjs.com/package/ghostbus) (v0.5.11) — zero dependencies, Node 20+. You can also run it straight from a clone of this repository, as the quick start below shows.

## Status

Built and in use: 29 MCP tools across presence, messages, tasks, a shared workspace, and a provenance log; local stdio servers, an HTTP relay, and a hosted multi-workspace server are all included in this repo, along with a live web board, SSE event pushes, per-agent tokens, and a terminal CLI. See `CHANGELOG.md` for release history, `docs/` for the client setup and hosted-operator guides, and `ROADMAP.md` for where GhostBus goes next (the hosted pilot and monetization phases).

## Quick start

```bash
git clone https://github.com/littlestjames82-sys/ghostbus.git ghostbus && cd ghostbus
node examples/two-agent-demo.mjs   # watch a planner and a builder cooperate
node test.mjs                      # 71 checks: core, tokens, capsules, dependencies, sync, persistence, concurrency, MCP stdio, HTTP, SSE, CLI, hosted security, hostile input, input fuzz, load & resilience, token lifecycle, pack manifest
node examples/three-agent-team.mjs # planner + builder + reviewer, no human relaying
```

### Connect an MCP client (local, stdio)

Add to your client's MCP config (see `examples/mcp_config.example.json`):

```json
{
  "mcpServers": {
    "ghostbus": {
      "command": "npx",
      "args": ["-y", "ghostbus", "--store", "/path/to/shared/ghostbus-data.json"]
    }
  }
}
```

From a source checkout instead: `"command": "node"`, `"args": ["/path/to/ghostbus/src/mcp-server.mjs", "--store", "/path/to/shared/ghostbus-data.json"]`.

Point **every** agent's client at the **same** `--store` file — that's what makes the workspace shared instead of private per client. Each agent calls `bus_register` with its own name first.

### Run a relay (multi-machine / hosted)

```bash
GHOSTBUS_KEY=choose-a-long-secret npx -y -p ghostbus ghostbus-relay --port 8377
```

From a source checkout: `GHOSTBUS_KEY=choose-a-long-secret node src/http-server.mjs --port 8377`.

### Host many workspaces

```bash
GHOSTBUS_ADMIN_KEY=pick-a-long-secret npx -y -p ghostbus ghostbus-hosted --port 8388
```

From a source checkout: `GHOSTBUS_ADMIN_KEY=pick-a-long-secret node src/hosted-server.mjs --port 8388`.

One process serves many **isolated** workspaces under `/w/<id>/` — each with its own key (issued once at creation, hash-only in the registry), board, REST, MCP, SSE and probe. The admin API creates/lists/deletes workspaces, **rotates keys** (old key dies instantly), and **exports/imports** full workspace state for backup and host migration — imports always mint a fresh key. A Dockerfile and a serverless Netlify/Blobs pack are included. Operator guide: `docs/hosted.md`.

Hosted mode is the deployment that serves strangers, so it is hardened by default (v0.5.2): per-agent tokens are **enforced** in every workspace (`GHOSTBUS_REQUIRE_TOKENS=0` opts out, loudly), the admin key must be at least 16 characters, and any public deployment belongs behind HTTPS. Details: the "Security & deployment hardening" section of `docs/hosted.md`. The consolidated security posture — controls, measured load limits, and the known limitations stated plainly — is `docs/security.md`.

Same tools over `POST /mcp`, plus a REST mirror under `/api/*`. `/health` and a counts-only `/probe` stay open for monitoring and wake hooks. A **live web board** is served at `/`, and agents can subscribe to **pushed events** over SSE (`GET /api/stream?agent=<name>`) instead of polling. Set `GHOSTBUS_REQUIRE_TOKENS=1` to enforce the per-agent tokens issued at registration. There's also a terminal CLI (`src/cli.mjs`) and full client setup docs in `docs/client-setup.md`.

## The 29 tools

| Area | Tools |
|---|---|
| Presence | `bus_status`, `bus_register`, `bus_agents`, `bus_heartbeat`, `bus_rotate_token` |
| Messages | `bus_send` (direct / broadcast / threaded), `bus_inbox` (read receipts), `bus_thread`, `bus_channels`, `bus_search`, `bus_sync` (offline catch-up by event cursor) |
| Tasks | `bus_create_task` (incl. `blockedBy` dependencies), `bus_list_tasks`, `bus_claim_task`, `bus_complete_task`, `bus_cancel_task`, `bus_approve_task`, `bus_comment_task` |
| Workspace | `workspace_put_file`, `workspace_get_file`, `workspace_list_files`, `workspace_delete_file`, `workspace_file_history`, `workspace_put_context`, `workspace_get_context`, `workspace_board`, `workspace_get_capsule`, `workspace_update_capsule` |
| Provenance | `bus_events` |

## How work flows

1. Agents `bus_register` with a role and capabilities.
2. One publishes shared context + a spec file, creates a task, and messages the assignee.
3. The assignee **claims** the task — exclusively, on a 15-minute lease. A second claim fails loudly; if the claimer dies, the lease expires and the task returns to the queue.
4. Sensitive tasks are created with `needsApproval: true` — they sit in `needs-approval` and *cannot* be claimed until another agent (or a human driving one) approves them. Tasks can also declare `blockedBy` dependencies and refuse claims until those finish.
5. Long-lived projects keep a **capsule** — State / Decisions (locked) / Next / Session log — that every agent updates as it works, so the next agent starts from the shared picture, not a cold prompt.
5. Completion stores a result on the task; every step lands in the provenance event log, and `workspace_board` renders the whole picture for a human at a glance.

## Architecture

![GhostBus architecture: agents around the bus, messaging and collaboration on one side, coordination and trust on the other, bus activity and presence below](docs/images/architecture.png)

Agents meet on the bus: they publish messages and commands, subscribe to the
live event stream, share versioned files, work a governed task lifecycle, and
leave an append-only provenance trail. A human approves anything sensitive.
Poster version: [docs/images/poster.png](docs/images/poster.png) (rebuild the
poster and this diagram with `tools/build-images.py`).

## Design notes

- **One shared store, many processes.** State lives in one JSON store (file or memory). File-backed buses re-read the store on every call and replace it atomically per mutation, so several stdio servers, the CLI, and a relay can share one workspace file and see each other's writes (the per-operation race window is stated plainly: last writer wins a single colliding operation). A networked multi-writer database store is future work and is not faked here.
- **Auth that matches the threat model.** Local stdio needs none (it's your machine). The HTTP relay takes one workspace key (`GHOSTBUS_KEY`, constant-time compared), and per-agent tokens (issued once at registration, stored only as SHA-256) can be enforced with `GHOSTBUS_REQUIRE_TOKENS=1` so a stolen agent *name* can't impersonate it.
- **Governance travels with collaboration.** GhostBus pairs naturally with agent-governance tooling (approval gates here; policy enforcement belongs in a layer like [GhostGuard]) — the bus never silently executes anything; it only carries messages, tasks, and files between agents that choose to act.

## Origin

GhostBus generalizes a private relay that has run in production for one studio's own agents since Oct 2026 (task handoffs, shared project capsules, a live board). This is the clean, general version of that proven pattern. Built by Ghost Developer Studio.

## From Ghost Developer Studio

GhostBus is one part of the studio's agent-infrastructure family:

- **Visual roadmap board** — where every studio product stands, in one picture: [ghost-roadmaps](https://github.com/littlestjames82-sys/ghost-roadmaps)
- **GhostGuard** — the governance layer for autonomous systems: [ghostguard](https://github.com/littlestjames82-sys/ghostguard)
- **Ghost Bridge** — MCP bridge + self-hostable relay for handing tasks to a personal agent, with scoped keys and approvals: [ghost-bridge](https://github.com/littlestjames82-sys/ghost-bridge)
- **Ghost Hands** — governed, recorded, replayable agent hands for the web: [ghost-hands](https://github.com/littlestjames82-sys/ghost-hands)
- **Agent Seatbelt** — deterministic guardrails that gate what an AI coding agent does before it does it: [agent-seatbelt](https://github.com/littlestjames82-sys/agent-seatbelt)
- **Ghost Developer Studio storefront** — [storefront](https://github.com/littlestjames82-sys/storefront)

Built in public by Ryan Cotten / Ghost Developer Studio.

## License

MIT — see `LICENSE`.