AgentBus

Local MCP event log and advisory lease coordinator for multi-agent workspaces.

When Cursor, Claude Code, Antigravity, Hermes, and other agents share a workspace, they usually coordinate through append-only files (log.md, sticky notes, Slack). That works until you need ordering, idempotency, cursors, schema validation, or file-edit mutexes.

AgentBus is a localhost sidecar: a Python MCP server backed by SQLite. Agents publish structured events; peers poll with since_id cursors. Advisory lease locks prevent concurrent edits. No orchestrator runtime lock-in.

v0.2 (July 2026): Events + advisory lease locks — publish, poll, status, lock_*. SSE subscribe and custom topics on the roadmap.

Note: PyPI names agentbus (NATS) and agentbus-mcp (blocked as too similar) are unavailable. Install as okf-agentbus (CLI command remains agentbus).

Why AgentBus?

Related MCP server: claude-sync

Install

pip install okf-agentbus

# Or from GitHub
pip install "okf-agentbus @ git+https://github.com/onicarps/agentbus@v0.2.3"

# Or clone for development
git clone https://github.com/onicarps/agentbus.git
cd agentbus
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

Quickstart

export AGENTBUS_WORKSPACE=/path/to/workspace
export AGENTBUS_PRODUCER_ID=my-agent

# Terminal A — MCP server (stdio)
agentbus serve --workspace "$AGENTBUS_WORKSPACE"

# Terminal B — publish a handoff
agentbus publish \
  --topic okf/handoff \
  --payload '{"from":"my-agent","to":"peer","summary":"Hello bus"}'

# Poll events
agentbus poll --topic okf/handoff --since-id 0

# Acquire an advisory lease before editing a shared file
agentbus lock acquire --resource "$AGENTBUS_WORKSPACE/log.md" --owner-id my-agent
agentbus lock status --resource "$AGENTBUS_WORKSPACE/log.md"
agentbus lock release --resource "$AGENTBUS_WORKSPACE/log.md" --lease-id <uuid> --owner-id my-agent

MCP setup

Use scripts/mcp-serve.sh so the workspace token is injected automatically:

{
  "mcpServers": {
    "agentbus": {
      "command": "/path/to/agentbus/scripts/mcp-serve.sh",
      "env": {
        "AGENTBUS_WORKSPACE": "/path/to/workspace",
        "AGENTBUS_PRODUCER_ID": "cursor"
      }
    }
  }
}

Client-specific templates:

MCP tools

Documentation

For full documentation, see the docs/ directory:

• MCP Schema & Event Reference

• Authentication

• Lease Locks Architecture

• End-to-End Walkthrough - Learn how a PM, Engineer, and QA agent coordinate.

• Client Capability Matrix - See how Cursor, Claude, and Antigravity compare.

Authentication

On serve, AgentBus writes an ephemeral token to {workspace}/.agentbus/token (mode 0600). Publish and lock mutations require a matching token via:

• scripts/mcp-serve.sh (recommended for MCP — reads workspace file, not stale env)

• AGENTBUS_TOKEN environment variable

• --token CLI flag

• auth_token MCP tool argument (optional; omit when using mcp-serve.sh)

Poll, status, and lock_status remain open. Set AGENTBUS_AUTH=off to disable during local development.

Details: docs/AUTH.md

Topics (v0.2)

Custom topics are planned — contributions welcome.

CLI reference

agentbus serve [--workspace PATH] [--rotate-token]
agentbus publish --topic TOPIC --payload JSON [--producer-id ID]
agentbus poll --topic TOPIC [--since-id N] [--limit N]
agentbus status [--producer-id ID]
agentbus token show|ensure|rotate
agentbus lock acquire|release|renew|status
agentbus project-log [--log-file log.md]   # optional markdown projection

Set AGENTBUS_WORKSPACE to avoid repeating --workspace.

Development

.venv/bin/pytest tests/ -q          # 40+ tests
.venv/bin/pytest tests/ --cov=agentbus --cov-report=term-missing

Project layout

src/agentbus/     # Python package
tests/            # pytest suite (40 tests)
docs/             # MCP schema, auth guide
examples/         # MCP client configs (Cursor, Claude, Hermes)
scripts/          # mcp-serve.sh wrapper

Roadmap

See ROADMAP.md. v0.2 ships events + advisory locks; v0.3 targets custom topics and HTTP transport.

Contributing

We want real-world use cases from teams running heterogeneous agent stacks. See CONTRIBUTING.md.

License

MIT — see LICENSE.