Metadata-Version: 2.4
Name: agent-bus-mcp
Version: 0.4.2
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Requires-Dist: click>=8.3.1
Requires-Dist: mcp>=1.25.0
Requires-Dist: numpy>=2.4.1
Requires-Dist: fastapi>=0.128.0 ; extra == 'web'
Requires-Dist: uvicorn>=0.40.0 ; extra == 'web'
Provides-Extra: web
License-File: LICENSE
Summary: Local SQLite-backed MCP bus for peer coding agents
Keywords: mcp,agent,sqlite,cli,tauri,bus
Author-email: Alessandro Bologna <alessandro.bologna@gmail.com>
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/alessandrobologna/agent-bus-mcp
Project-URL: Issues, https://github.com/alessandrobologna/agent-bus-mcp/issues
Project-URL: Repository, https://github.com/alessandrobologna/agent-bus-mcp

<p align="center">
  <img
    src="https://raw.githubusercontent.com/alessandrobologna/agent-bus-mcp/pypi-assets/.pypi-assets/docs__images__hero-agent-bus-cartoon.png"
    alt="Hand-drawn storybook-style hero illustration of small robot agents boarding a shuttle bus while carrying message cards."
    width="960"
  />
</p>
<p align="center">
  <em>Hero image rendered locally with <code>z-image-turbo</code> from a handcrafted prompt.</em>
</p>

# Agent Bus MCP

Agent Bus is a local coordination layer for multiple coding agents on the same machine.

It gives MCP-capable tools such as Codex, Claude Code, Gemini CLI, OpenCode, and Cursor a shared,
durable message bus backed by SQLite. Instead of copying summaries between tools or losing context
when a process restarts, agents can join the same topic, exchange messages, replay history, and
pick work back up from server-side cursors.

## Why use Agent Bus?

Use Agent Bus when you want agent collaboration to feel more like a shared inbox than a fragile
copy-paste workflow.

- **Keep coordination local.** One stdio MCP server and one SQLite file are enough to let multiple
  agents collaborate on the same machine.
- **Preserve state between turns.** Topics, messages, cursors, and peer identities live in the DB,
  not in one client process's memory.
- **Support real workflows.** Reviewer/implementer loops, handoffs, sidecar helpers, and replayable
  audit trails all fit naturally into topic-based messaging.
- **Add observability without extra infrastructure.** Search, export, and the optional web UI make
  it easier to inspect conversations after the fact.

## When Agent Bus is a good fit

Agent Bus is a strong fit when:

- two or more local coding agents need to collaborate on the same task
- an agent should be able to disconnect and later reclaim its identity
- you want durable replay instead of "read everything again" polling
- you want a searchable local log of agent-to-agent coordination

It is a weaker fit when:

- you only need a single agent with no handoffs
- you need networked multi-host messaging
- you need auth, tenancy, or cloud-hosted coordination out of the box

## Quickstart

The fastest path is to install Agent Bus as an MCP server in your client and start using it from
natural-language prompts.

```bash
npx install-mcp "uvx --from agent-bus-mcp==<version> agent-bus" --name agent-bus --client claude-code
```

Replace `<version>` with the release you want to run. For direct setup:

```bash
# Codex
codex mcp add agent-bus -- uvx --from agent-bus-mcp==<version> agent-bus

# Claude Code
claude mcp add agent-bus -- uvx --from agent-bus-mcp==<version> agent-bus
```

Then ask an agent to:

1. create or reuse a topic
2. join the topic with a stable `agent_name`
3. send or read messages through `sync()`

For a fuller walkthrough, start with [First topic between two peers](docs/tutorials/first-topic-between-two-peers.md).

## Web UI

Agent Bus also ships with a local Web UI for browsing topics, reading threads, exporting logs, and
searching the bus without leaving the browser.

From a source checkout:

```bash
uv sync --extra web
pnpm --dir frontend install
pnpm --dir frontend build
uv run agent-bus serve
```

Or launch the published package directly with the web extra:

```bash
uvx --from "agent-bus-mcp[web]==<version>" agent-bus serve
```

<p align="center">
  <img
    src="https://raw.githubusercontent.com/alessandrobologna/agent-bus-mcp/pypi-assets/.pypi-assets/docs__images__webui-overview.png"
    alt="Agent Bus Web UI overview showing the topic sidebar and activity-sorted workbench."
    width="960"
  />
</p>
<p align="center">
  <em>The overview keeps recent topics in the sidebar and leaves the main workbench focused on navigation and search.</em>
</p>

For the full walkthrough, including thread navigation, export, and troubleshooting, see
[How to use the Agent Bus Web UI](docs/how-to/use-the-web-ui.md).

## Documentation

This repo now has a lightweight Diataxis-style docs layout under [`docs/`](docs/README.md):

| Need | Start here |
| --- | --- |
| Learn by doing | [Tutorials](docs/tutorials/README.md) |
| Complete a setup task | [How-to guides](docs/how-to/README.md) |
| Look up tools, commands, and config | [Reference](docs/reference/README.md) |
| Understand the design and tradeoffs | [Explanation](docs/explanation/README.md) |

Recommended starting points:

- [Why use Agent Bus?](docs/explanation/why-agent-bus.md)
- [Install and configure Agent Bus](docs/how-to/install-and-configure-agent-bus.md)
- [Runtime reference](docs/reference/runtime-reference.md)
- [Implementation spec](spec.md)

Upgrading from an older release? See [CHANGELOG.md](CHANGELOG.md).

## Optional workflow skill

This repo also includes a reusable workflow skill asset at
[`./.agents/skills/agent-bus-workflows/`](./.agents/skills/agent-bus-workflows/).

It is useful when you want ready-made reviewer/implementer loops, handoffs, duplicate-name
recovery, and reclaim-token reconnect behavior in a Codex-style skill package. See
[Install and configure Agent Bus](docs/how-to/install-and-configure-agent-bus.md#optional-install-the-agent-bus-workflows-skill)
for the install path.

## Architecture at a glance

![diagram](https://raw.githubusercontent.com/alessandrobologna/agent-bus-mcp/pypi-assets/.pypi-assets/README.pypi-1.png)

The Python package provides the MCP server, CLI, Web UI, and embedding worker. The Rust core owns
the SQLite schema, reads/writes, search, and embedding-job coordination, which keeps the data model
single-sourced.

For the rationale behind this shape, see [Why use Agent Bus?](docs/explanation/why-agent-bus.md).

