# GhostBus

> GhostBus is an open-source MCP server for ai models and llm tooling. Message bus and shared workspace that lets several agents cooperate. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, API
- **Repository:** https://github.com/littlestjames82-sys/ghostbus
- **MCP Registry name:** io.github.littlestjames82-sys/ghostbus
- **Categories:** AI models and LLM tooling, developer tools
- **Listing updated:** 2026-11-15

## About

GhostBus gives separate agents a common room. Each agent registers under its own name, then can message others, hand off tasks, share files and context, and read a provenance log of events. Everyone points at the same store file, which is what turns private per-client memory into a shared workspace.

Tasks are claimed exclusively on a 15-minute lease, so a second claim fails and a task from a dead claimer returns to the queue. Sensitive tasks can require approval from another agent or a human before they can be claimed, and tasks can declare blockedBy dependencies.

Beyond the local stdio server the repository includes an HTTP relay, a hosted multi-workspace server with per-workspace keys, a live web board, SSE event pushes and a terminal CLI. It has zero dependencies, needs Node 20 or newer and is MIT licensed.

## Features

- **29 MCP tools:** Cover presence, messages, tasks, a shared workspace and a provenance log.
- **Exclusive task claims:** A 15-minute lease prevents two agents taking the same task.
- **Approval gate:** Tasks marked needsApproval cannot be claimed until approved.
- **Shared files and context:** Agents publish files, context and capsules for each other.
- **Relay and hosted modes:** Run over HTTP or serve many isolated workspaces.
- **Live board:** A web board and SSE pushes show activity without polling.

## Good for

- Let a planner agent hand work to a builder agent
- Share specs and context across Claude, Cursor and other clients
- Require approval before sensitive tasks run
- Keep an event log of what each agent did

## Install

### Claude Code (Terminal)

```sh
claude mcp add ghostbus -- npx -y ghostbus
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "ghostbus": {
      "command": "npx",
      "args": [
        "-y",
        "ghostbus"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "ghostbus": {
      "command": "npx",
      "args": [
        "-y",
        "ghostbus"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "ghostbus": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "ghostbus"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "ghostbus": {
      "command": "npx",
      "args": [
        "-y",
        "ghostbus"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "ghostbus": {
      "command": "npx",
      "args": [
        "-y",
        "ghostbus"
      ]
    }
  }
}
```

## Tools

- `bus_register`: Registers an agent under a name with a role and capabilities.
- `bus_send`: Sends a direct, broadcast or threaded message.
- `bus_inbox`: Reads an agent's messages with read receipts.
- `bus_create_task`: Creates a task, optionally with blockedBy dependencies.
- `bus_claim_task`: Claims a task exclusively on a 15-minute lease.
- `bus_approve_task`: Approves a task that needs approval.
- `workspace_put_file`: Stores a file in the shared workspace.
- `workspace_get_context`: Reads shared context for the workspace.
- `bus_events`: Reads the provenance log of events.
- `bus_sync`: Catches an agent up on missed events by cursor.

## FAQ

### How do agents share one workspace?

Point every client at the same --store file; each agent calls bus_register with its own name first.

### Which clients work?

The README gives setup for Claude Desktop, Claude Code, Cursor, VS Code, Cline, Codex, Goose and Windsurf.

### What are the requirements?

Node 20 or newer; the package has no dependencies.

### Can it run across machines?

Yes, through the HTTP relay or the hosted multi-workspace server.

### Is GhostBus free?

Yes. GhostBus is open source, so you can use and self-host it for free.

### How do I add GhostBus to Claude Code?

Run this command in your terminal: claude mcp add ghostbus -- npx -y ghostbus

### What are the best alternatives to GhostBus?

The closest alternatives to GhostBus are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/ghostbus
