AgentBus

The Zero-Daemon, SQLite-Backed Event Bus & Visual Cockpit for Multi-Agent Coding.

When Cursor, Claude Desktop, Antigravity, terminal bots (Hermes, Aider), and custom Python scripts work together in the same workspace, coordinating them usually devolves into messy, append-only log.md files or heavy cloud dashboards.

AgentBus gives your AI agents a fast, typed, local pub/sub highway backed by a single SQLite file (.agentbus/events.db) and gives you an interactive God View Mission Control TUI to watch every handoff, trace execution lineage, and approve dangerous actions in real time.

⚡ 30-Second Quickstart (The "Ah-Ha" Moment)

You don't need complex configurations or Docker daemons to see AgentBus in action.

1. Install

# Fastest: Installs AgentBus and configures your path automatically
curl -sSL https://raw.githubusercontent.com/onicarps/agentbus/main/install.sh | bash

(Or via package manager: pip install okf-agentbus or pipx install okf-agentbus — the interactive TUI monitor is bundled out-of-the-box!)

2. Launch the Visual Monitor (Terminal A)

agentbus monitor

(Or use the standalone command: agentbus-monitor)

You are now in the God View TUI dashboard:

• Live Event Stream: Watch real-time multi-agent activity as it occurs.
• Trace Waterfall: Inspect trace_id lineage and parent-span relationships.
• HITL Approvals: Review pending approvals with one-keystroke hotkeys ([a] approve / [r] reject).

3. Send Your First Message (Terminal B)

Open another terminal in the same folder and publish a handoff event:

agentbus publish \
  --topic okf/handoff \
  --payload '{"from":"cursor","to":"claude","summary":"Added auth endpoints; please review and write tests."}'

👉 Look back at Terminal A: the event immediately pops up on your monitor!

🛠️ Why AgentBus?

📦 Fresh Boot & Installation Guide

AgentBus requires Python 3.11+. The God View interactive monitor (rich + textual) is installed automatically with the base package.

Option A: 1-Line Universal Installer (Recommended for fresh systems)

Handles fresh boots, non-root environments, and Linux PEP 668 (externally-managed-environment) automatically:

curl -sSL https://raw.githubusercontent.com/onicarps/agentbus/main/install.sh | bash

Option B: Standalone CLI Tool (pipx or uv)

If you prefer isolated CLI tools without creating project virtual environments:

# Using uv (fastest)
uv tool install okf-agentbus

# Using pipx
pipx install okf-agentbus

Option C: In an existing virtual environment

If you have an active project virtual environment (.venv):

pip install -U okf-agentbus

💡 Troubleshooting "Python / Virtual Environment" Issues: On modern Linux (Ubuntu 24.04+, Debian 12+) and macOS Homebrew, system Python restricts bare pip install to protect OS packages (PEP 668). If you see error: externally-managed-environment, either run the 1-line curl installer above (which creates an isolated tool runtime in ~/.local/share/agentbus/venv and symlinks to ~/.local/bin/agentbus) or use pipx install okf-agentbus.

🔌 Connecting Your AI Coding Agents

AgentBus speaks standard Model Context Protocol (MCP) over stdio as well as standard CLI commands.

1-Click Auto-Configuration

Navigate to your project workspace and run:

agentbus init --apply --producer-id my-agent

AgentBus scans for installed tools (Cursor, Claude Desktop, Antigravity) and automatically generates the necessary MCP configuration!

Manual IDE Configurations

For Cursor (~/.cursor/mcp.json or .cursor/mcp.json)

{
  "mcpServers": {
    "agentbus": {
      "command": "agentbus",
      "args": ["mcp-serve"],
      "env": {
        "AGENTBUS_WORKSPACE": "/path/to/your/project",
        "AGENTBUS_PRODUCER_ID": "cursor"
      }
    }
  }
}

For Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "agentbus": {
      "command": "agentbus",
      "args": ["mcp-serve"],
      "env": {
        "AGENTBUS_WORKSPACE": "/path/to/your/project",
        "AGENTBUS_PRODUCER_ID": "claude"
      }
    }
  }
}

Once connected, your AI agents will automatically see tools like:

• agentbus_publish — publish task updates, handoffs, and questions.
• agentbus_poll — check for incoming assignments.
• agentbus_lock_acquire / agentbus_lock_release — prevent file edit collisions.

💡 Practical Examples for Beginners & Intermediates

Example 1: CLI Coordination (Zero Code)

Simulate two agents working together directly from the shell:

# Agent A publishes a completed task:
agentbus publish \
  --topic okf/handoff \
  --payload '{"from":"alice","to":"bob","summary":"Refactored database models"}'

# Agent B polls for new tasks:
agentbus poll --topic okf/handoff --since-id 0

Example 2: Python Script (Publishing & Polling)

Integrate any custom Python agent or bot in 5 lines:

from pathlib import Path
from agentbus.rbac import ensure_default_roles
from agentbus.store import EventStore

# Connect to current project workspace
workspace = Path.cwd()
ensure_default_roles(workspace)  # install the local role policy first
store = EventStore(workspace)

# Publish an event
event, _ = store.publish(
    topic="okf/handoff",
    producer_id="codex",
    schema_version="1.0",
    payload={"from": "codex", "to": "all", "summary": "Job completed successfully"},
)
print(f"Published event #{event.event_id}")

# Poll new events
messages = store.poll("okf/handoff", since_id=0)
for ev in messages["events"]:
    print(f"[{ev['event_id']}] {ev['payload']['summary']}")

store.close()

Example 3: Human-in-the-Loop (HITL) Safety Intercepts

Catch dangerous AI operations (e.g. database migrations, shell scripts, deletions) before they execute:

# 1. Register an intercept rule: any handoff containing 'DROP' requires human approval
agentbus config set-intercept --topic okf/handoff --contains "DROP" --ttl-minutes 30

# 2. When an agent tries to publish:
agentbus publish \
  --topic okf/handoff \
  --payload '{"from":"agent","to":"db","summary":"DROP TABLE users"}'
# => Status becomes: PENDING_APPROVAL

# 3. View and approve/reject it in the TUI:
agentbus monitor
# Press [A] to approve or [R] to reject!

Example 4: Preventing File Collisions with Advisory Locks

When multiple agents write code at the same time, they can accidentally overwrite each other. Use advisory leases:

# Agent 1 locks a file before editing:
agentbus lock acquire --resource src/models.py --owner-id agent-1 --ttl 300

# Agent 2 checks lock status:
agentbus lock status --resource src/models.py

# Agent 1 releases the lock when finished:
agentbus lock release --resource src/models.py --owner-id agent-1 --lease-id <LEASE_ID>

Example 5: 1-Click Multi-Agent Swarm (agentbus up)

Instead of opening 5 terminal windows, orchestrate your agents, file watchers, and monitor together:

# 1. Generate default .agentbus/swarm.yaml
agentbus up --init

# 2. Start the swarm (daemons + God View monitor)
agentbus up

# 3. Check running background workers
agentbus ps

# 4. Tear down the swarm cleanly
agentbus down

📚 Complete Examples Catalog

Check out the examples/ folder for fully isolated, executable Python scripts:

• 01_core_pub_sub.py — Fundamental publish and poll flow.
• 02_hitl_intercepts.py — Catching sensitive payloads for human sign-off.
• 03_swarm_rbac.py — Swarm role-based topic permissions and identity tokens.
• 04_sla_timeouts.py — Automated dead-letter routing when an agent ghosts.
• 05_observability.py — Distributed trace waterfall lineage (trace_id, parent_span_id).
• 06_distributed_context.py — Sharing large artifacts/diffs via content hashing.
• 07_pydantic_schemas.py — Validating topic payloads with Pydantic models.
• 08_god_view.py — Passive OS filesystem, shell, and MCP call observation.
• 09_langgraph_bridge.py — A LangGraph-node handoff skeleton.
• 10_crewai_bridge.py — A CrewAI-task handoff skeleton.

See the Examples Guide for full documentation on each recipe.

⌨️ CLI Cheat Sheet

📖 Deep-Dive Documentation

• End-to-End Walkthrough (Alice, Bob, & Charlie)
• Model Context Protocol (MCP) Tool Schema
• AgentID Security Model & Identity System
• Client Compatibility Matrix
• PostHog Outbound Telemetry
• Release Runbook & Process
• Roadmap

📄 License

MIT — see LICENSE.