AgentBus

A private, local walkie-talkie and dashboard for your AI coding assistants.

If you use AI coding tools like Cursor, Claude Code, VS Code, or custom scripts on the same project, you have likely run into the coordination problem:

• Overwritten code: Two AI assistants edit the same file at the same time and erase each other's changes.

• Lost context: A plan or decision stays trapped in one chat window, forcing you to copy and paste text back and forth.

• Risky actions: An assistant prepares to run a database migration or delete files before you have had a chance to look it over.

• Heavy infrastructure: Setting up cloud message brokers or Docker containers just to let local tools talk to each other is complicated, slow, and expensive.

AgentBus solves this right inside your project folder. It gives your AI tools a fast, private messaging channel backed by a single local database file (.agentbus/events.db), and gives you an interactive visual dashboard in your terminal to watch every handoff, track progress, and approve sensitive actions in real time.

No cloud accounts. No subscriptions. No background servers required for local coordination.

Quickstart in 60 Seconds

1. Install AgentBus

Choose the method that works best for your system:

Option A: Package Manager (Recommended)

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

# Using pipx
pipx install okf-agentbus

Option B: Standalone Installer Script

# 1. Download install.sh pinned to release commit 0f6d389
curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/onicarps/agentbus/0f6d389622a168b78eb3bdc3b02729c5bc4680aa/install.sh -o install.sh

# 2. Verify script SHA-256 and run with release v0.28.0:
# On Linux:
echo "03e64e9bb7e252c072ba77e0cc62324f3e3d34a9c4aaeb4886a0e897c80528b2  install.sh" | sha256sum --check && AGENTBUS_PACKAGE_NAME="okf-agentbus==0.28.0" bash install.sh
# On macOS:
echo "03e64e9bb7e252c072ba77e0cc62324f3e3d34a9c4aaeb4886a0e897c80528b2  install.sh" | shasum -a 256 --check && AGENTBUS_PACKAGE_NAME="okf-agentbus==0.28.0" bash install.sh

Supply-Chain Verification Note: The SHA-256 checksum verifies the install.sh script itself. It does not verify downstream artifacts (such as the separately downloaded uv installer when uv is not already installed, or the fetched Python package wheels and their dependencies). For audited environments with strict verification policies, install pinned packages using your standard package manager, lockfiles, or internal artifact mirror.

Path Note: The installer places the executable in ${XDG_BIN_HOME:-$HOME/.local/bin} and updates your shell profile for new sessions. For your current terminal, make sure that directory is on your PATH (for example: export PATH="${XDG_BIN_HOME:-$HOME/.local/bin}:$PATH").

2. Connect Your Project (Terminal A)

Go to your project directory and run the companion setup:

cd ~/my-project

# Run the setup assistant (finds installed tools and asks to connect them)
agentbus

Now open the visual dashboard:

agentbus monitor

You are now in the terminal dashboard:

• Live Feed: Watch messages and tasks as they are sent between tools.

• Task History: Inspect which agent started a task and who is continuing it.

• One-Key Approvals: Press a to approve or r to reject actions waiting for human review.

(Note: In automated scripts or CI pipelines, running agentbus on a fresh project initializes it non-interactively with project-scoped tool discovery applied, or outputs JSON status if already set up. Automated setup only changes project files like .cursor/mcp.json or .vscode/mcp.json. Changes to global user files require the explicit flag agentbus connect --apply --allow-user-scope.)

3. Send Your First Message (Terminal B)

Open a second terminal window in the same folder and publish a message:

agentbus publish \
  --topic okf/handoff \
  --producer-id local-user \
  --payload '{"from":"local-user","to":"reviewer","summary":"Built the auth endpoints. Ready for review."}'

Switch back to Terminal A: your message appears immediately on your dashboard screen.

Related MCP server: Hivemind

How It Works in Practice

Here is an everyday example of how AgentBus helps two different AI assistants work together smoothly:

[Claude Code] ---------------------------> [AgentBus] ---------------------------> [Codex CLI]
(Writes code in terminal)           (Local events.db)                 (Runs automated audit)
       |                                   |                                     |
       | 1. Takes advisory lease           |                                     |
       |    on src/auth.py                 |                                     |
       | 2. Updates endpoints              |                                     |
       | 3. Publishes handoff event -----> | Stores event #42                    |
       |                                   | Notifies subscribers -------------> | 4. Reads event #42
       |                                   |                                     | 5. Audits src/auth.py
       |                                   | <--- 6. Publishes review passed --- | 6. Sends completion report
       |                                   |
                               [Your Terminal Cockpit]
                         (Watch handoffs live, approve/reject)

1. Claude Code finishes writing an authentication feature and publishes a handoff event to AgentBus.

2. AgentBus logs the message to your project's local .agentbus/events.db file.

3. Codex CLI polls the bus, sees the handoff assigned to it, and runs verification checks.

4. You watch the entire conversation unfold on your terminal dashboard (agentbus monitor) without needing to switch windows or copy-paste prompts.

Five Core Capabilities

1. Live Visual Dashboard

Instead of wondering what your AI assistants are doing across separate editor windows, run agentbus monitor. You get a clean, high-density live view of:

• Active messages and task handoffs.

• Task relationships (trace_id) showing which action triggered another.

• Pending requests waiting for human approval.

• Active file reservations.

2. File Reservations (Advisory Leases)

Prevent two AI assistants from editing the same file at the same time:

# Agent 1 checks out models.py for 5 minutes (300 seconds):
agentbus lock acquire --resource "$PWD/src/models.py" --owner-id agent-1 --ttl-seconds 300

# Other tools can check if someone else is currently editing the file:
agentbus lock status --resource "$PWD/src/models.py"

# When Agent 1 finishes, it releases the reservation:
agentbus lock release --resource "$PWD/src/models.py" --owner-id agent-1

Advisory Scope Note: File leases are advisory. Cooperating tools and agents check status and honor active leases before writing. AgentBus coordinates permissions across agents but does not intercept low-level operating system file calls or block external text editors.

3. Human Approval Gates

Hold high-risk actions (such as database migrations, deletions, or external deployments) until a human gives permission:

# 1. Create a safety rule: any handoff containing 'DROP' or 'MIGRATE' requires approval
agentbus config set-intercept --topic okf/handoff --contains "DROP" --ttl-minutes 30
agentbus config set-intercept --topic okf/handoff --contains "MIGRATE" --ttl-minutes 30

# 2. When an agent publishes a matching action, AgentBus pauses it in PENDING_APPROVAL status.
# 3. Downstream agents will not execute the action until you approve it.
# 4. In your terminal dashboard, press 'a' to approve or 'r' to reject.
# (Or approve via the command line with an authorized role):
# agentbus approve <event_id> --reviewer-id agy
# agentbus reject <event_id> --reviewer-id agy --reason "Needs schema migration plan"

How Approvals Work: Approval rules hold matching events published to AgentBus. They do not intercept arbitrary shell commands or out-of-band actions. Tools coordinate safety by publishing planned actions as bus events and waiting for human sign-off before proceeding. Reviewer Roles: Approving or rejecting events requires a reviewer mapped to a role with can_approve: true in .agentbus/roles.yaml (such as the default architect role mapped to agy, or configuring a reviewer in producers). The initial setup configures the default user as an engineer, which cannot approve events without an authorized reviewer role.

4. Automatic Project Documentation

Do not lose progress when an AI assistant's chat history clears. AgentBus can convert raw coordination messages into structured Markdown notes:

• agentbus distill: Materializes recent okf/handoff events into deterministic concept documents under okf/handoffs/YYYY/MM/, indexed by a bounded okf/log.md.

• agentbus project-log: In an OKF workspace with default settings, runs the bounded distiller to update okf/log.md and partitioned concepts; in non-OKF workspaces, appends recent handoffs to the root log.md.

# Save recent handoffs into organized documentation:
agentbus distill --limit 100

# Update the project changelog:
agentbus project-log

This leaves your team with a durable, human-readable paper trail of what was built, why, and by whom.

5. Verifiable Message History

Retained events are linked using a cryptographic SHA-256 hash chain (starting from the workspace genesis checkpoint or post-migration cutover boundary). You can check hash continuity across stored events at any time:

agentbus verify

Integrity Scope Note: agentbus verify checks internal hash continuity across retained events against the checkpoint stored in the database. Because pre-hash legacy rows serve as the initial unhashed checkpoint and a local writer could recompute the entire chain, detecting an externally recomputed database requires comparing the reported head hash against an external record (such as a git commit hash or external log).

Connecting Your AI Tools (Model Context Protocol)

AgentBus supports the open Model Context Protocol (MCP) over standard input/output (stdio). This allows tools like Cursor, Claude Code, and VS Code to talk to AgentBus natively.

Automatic Setup: Discover, Preview, Connect

AgentBus includes built-in discovery for popular AI tools. Discovery is completely safe and read-only by default:

# 1. Discover: See what tools exist on your system and what is already connected
agentbus discover
agentbus discover --json

# 2. Preview: Plan configuration changes without writing any files
agentbus connect

# 3. Apply: Connect detected auto-connect tools for the current project
agentbus connect --apply

# 4. Verify: Test that the connection command successfully communicates
agentbus connect --apply --verify

# Optional: Connect opt-in tools that default to auto_connect: false
agentbus connect --apply --client claude-code-project
agentbus connect --apply --client codex-project

# Optional: Connect global user tools (in interactive terminals you can confirm via prompt; non-interactive runs require --allow-user-scope)
agentbus connect --scope user --apply --allow-user-scope

(Note: Standard bulk runs with agentbus connect --apply configure auto-connect tools such as Cursor and VS Code. Opt-in tools like Claude Code (--client claude-code-project or --client claude-code-user) and Codex project (--client codex-project) declare auto_connect: false and are connected by specifying their client name. For user-scope files, interactive terminals prompt for confirmation, while non-interactive runs require --allow-user-scope.)

When you inspect your tools, AgentBus clearly reports their status:

• Configured: The configuration file matches what AgentBus expects.

• Differs: A configuration already exists but has different settings. AgentBus will not silently overwrite it.

• Awaiting Approval: The configuration file was created or updated, but your AI tool needs to be restarted or needs you to click "Allow" in its settings.

• Command Verified: When run with --verify, AgentBus proved that the configured command starts and answers MCP requests properly.

Safety Guarantees

• Zero unexpected writes: agentbus discover and agentbus connect (without --apply) never write, modify, or delete any files on your computer.

• One bounded version probe: agentbus connect and agentbus init --apply may run a single time-boxed opencode --version (with a temporary, isolated HOME) to tell the OpenCode v1 and v2 layouts apart. agentbus discover and dry-run agentbus init do not launch client CLIs or start the MCP server, but command resolution may run bounded validation probes.

• Conditional rollback: Before each replacement AgentBus re-checks the file's SHA-256 digest and reports file_created_externally, file_deleted_externally, or file_modified_externally instead of overwriting a concurrent edit. If a later write fails, rollback restores only files that still match what AgentBus wrote and reports a conflict for anything changed or deleted since; outside work is never clobbered.

• Automatic backups: When replacing an existing configuration file, AgentBus creates a unique backup file in the same directory (such as .cursor/mcp.json.agentbus.bak.<timestamp>.<pid>). Newly created files are not backed up. If an error occurs during an existing file's write, it makes a best-effort rollback.

• Secret protection: Passwords, API keys, and sensitive environment variables are automatically masked as [REDACTED] in terminal displays, logs, and JSON outputs.

• Safe file replacement: Configuration files are written to a temporary file first and replaced atomically per file so a crash during write does not leave a half-written file. Multi-file installations proceed sequentially, so crashes or non-cooperating writers can still leave partial multi-file state.

• Process locking: Setup operations use an advisory lock file (.agentbus/init.lock) so two setup commands running at the same time cannot corrupt each other.

Supported Tools

• Cursor: Project configuration (.cursor/mcp.json) and user configuration (~/.cursor/mcp.json).

• Claude Desktop: Linux, macOS, and Windows configuration files.

• Claude Code: Project configuration (.mcp.json) and user configuration (~/.claude.json).

• Codex CLI: Project configuration (.codex/config.toml) and global settings (~/.codex/config.toml).

• VS Code: Project configuration (.vscode/mcp.json, using the standard servers schema).

• Gemini: AgentBus writes the legacy user configuration (~/.gemini/config/mcp_config.json) for compatibility. Gemini CLI reads ~/.gemini/settings.json; add AgentBus to that file manually.

• Goose: User configuration (${XDG_CONFIG_HOME:-~/.config}/goose/config.yaml, %APPDATA%\Block\goose\config\config.yaml on Windows) under the extensions map. AgentBus rewrites only extensions.agentbus with a round-trip YAML writer that preserves comments, anchors, and key order, and refuses multi-document, custom-tag, recursive-anchor, or duplicate-key files.

• Cline CLI: User configuration (~/.cline/data/settings/cline_mcp_settings.json) with "disabled": false.

• Mistral Vibe: Project configuration (.vibe/config.toml) and user configuration (${VIBE_HOME:-~/.vibe}/config.toml). AgentBus updates the matching [[mcp_servers]] element in place and preserves every other table and comment.

• GitHub Copilot CLI: User configuration (~/.copilot/mcp-config.json) with "type": "local" and "tools": ["*"].

• OpenCode: Project (opencode.json) and user (${XDG_CONFIG_HOME:-~/.config}/opencode/opencode.json) configuration. OpenCode ships two incompatible layouts: v1 stores servers under mcp with enabled, v2 under mcp.servers with disabled. AgentBus selects one from --client opencode-v1|opencode-v2, then the config $schema, then a bounded opencode --version probe, then the file structure, and refuses to guess when the signals are missing or disagree.

• Qwen Code: Project (.qwen/settings.json) and user (~/.qwen/settings.json) configuration.

Manual Tool Configuration

If you prefer editing configuration files by hand, you can add AgentBus directly.

RBAC Producer Authorization Note: In a workspace with role-based access control enabled (.agentbus/roles.yaml), any AGENTBUS_PRODUCER_ID you configure (such as local-user) must have a corresponding role mapping under producers: (for example: producers: { local-user: engineer }). If roles.yaml exists and the configured producer is not listed, publish calls will return 403 Forbidden. You can change local-user in the snippets below to any producer ID that already has an authorized role mapping. agentbus connect never creates or edits .agentbus/roles.yaml: connecting a client does not grant a producer role. Workspaces without an active RBAC configuration, or with AGENTBUS_DISABLE_RBAC=1 outside protected identity mode, keep working as before.

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

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

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

{
  "servers": {
    "agentbus": {
      "type": "stdio",
      "command": "agentbus",
      "args": ["mcp-serve"],
      "env": {
        "AGENTBUS_WORKSPACE": "/path/to/your/project",
        "AGENTBUS_PRODUCER_ID": "local-user"
      }
    }
  }
}

[mcp_servers.agentbus]
command = "agentbus"
args = ["mcp-serve"]

[mcp_servers.agentbus.env]
AGENTBUS_WORKSPACE = "/path/to/your/project"
AGENTBUS_PRODUCER_ID = "local-user"

(Place this configuration in your workspace at .codex/config.toml for project scope, or in ~/.codex/config.toml for user global scope. Note: Codex loads project-scope .codex/config.toml only for trusted projects; for untrusted projects, trust the workspace or configure the user-scope file ~/.codex/config.toml so AgentBus is available).

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

Once connected, your AI tools gain these functions:

• agentbus_publish: Send task updates, questions, and handoffs.

• agentbus_poll: Check for incoming tasks assigned to them.

• agentbus_lock_acquire / agentbus_lock_release: Reserve files before editing.

• agentbus_review / agentbus_approve / agentbus_reject: Review and approve actions that need human permission.

Code Examples

AgentBus works seamlessly with Python, TypeScript/Node.js, and shell scripts.

Python SDK

Integrate custom Python agents, scripts, or LangChain/CrewAI tools in a few lines:

from pathlib import Path
from agentbus.store import EventStore

# Connect to the SQLite bus in the current project directory
store = EventStore(Path.cwd())

# Send a message to other agents
event, _ = store.publish(
    topic="okf/handoff",
    producer_id="local-user",
    schema_version="1.0",
    payload={"from": "local-user", "to": "reviewer", "summary": "API models updated"},
)
print(f"Published event #{event.event_id}")

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

store.close()

TypeScript / Node.js SDK

For Node.js projects, install @agentbus/agentbus-client:

npm install @agentbus/agentbus-client

Prerequisites: Node.js 18+ and the agentbus command available on your PATH.

import { AgentBus } from "@agentbus/agentbus-client";

async function main() {
  const bus = new AgentBus({
    workspace: process.cwd(),
    topics: ["okf/handoff"],
  });

  // Register listener before connecting so you do not miss initial events
  bus.on("okf/handoff", (payload, meta) => {
    console.log(`[Event #${meta.event_id}] From: ${payload.from} -> ${payload.summary}`);
  });

  await bus.connect();

  process.on("SIGINT", async () => {
    await bus.disconnect();
    process.exit(0);
  });
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Comparison: Why AgentBus?

Technical Architecture (Under the Hood)

AgentBus is designed to stay out of the way for simple local scripts while remaining reliable under multi-process workloads:

• Fast Lazy-Loaded CLI: A 3-tier lazy-loaded console entrypoint strips heavy imports (rich, textual, mcp, cryptography) from the hot command path, keeping startup latency low for commands like publish and poll.

• SQLite Transactional Concurrency: Multi-process read concurrency with serialized atomic writes using WAL journal mode on POSIX platforms. On Windows, SQLite defaults to MEMORY journal mode to reduce file locking contention under antivirus and EDR software (which offers best-effort operation but has weaker hard-crash durability than WAL or DELETE); you can override the journal mode on any platform via the AGENTBUS_SQLITE_JOURNAL environment variable (e.g. WAL, DELETE, or MEMORY). Multiple agents can read concurrently with standard SQLite transaction isolation.

• Materialized Projections: Total, latest, pending-approval, SLA, and topic counters are maintained in transaction-scoped tables, providing fast status queries without full-table scans.

• Embedded-First Architecture: For standard local pub/sub, state is stored directly in .agentbus/events.db (with auxiliary state files in .agentbus/). No background daemons are required unless you explicitly launch background worker processes via agentbus up -d.

• OKF v0.2 Native: Designed to integrate with the Open Knowledge Format standard for agent memory, roles, and handoffs.

CLI Reference

Daily Essentials

Tool Discovery & Connection

File Reservations (Advisory Leases)

Human Safety & Approvals

Documentation & Maintenance

Swarm Worker Daemons (Optional)

Examples and Guides

Explore complete, ready-to-run examples in the examples/ folder:

• 01_core_pub_sub.py - Basic publish and poll workflow.

• 02_hitl_intercepts.py - Pausing sensitive actions for human approval.

• 03_swarm_rbac.py - Topic permissions and security roles.

• 04_sla_timeouts.py - Automated routing when an assistant stops responding.

• 05_observability.py - Distributed trace waterfalls (trace_id, parent_span_id).

• 06_distributed_context.py - Sharing large files and diffs via content hashing.

• 07_pydantic_schemas.py - Validating message payloads with Pydantic.

• 08_god_view.py - File system, shell, and MCP observation.

• 09_langgraph_bridge.py - Bridging LangGraph nodes with AgentBus.

• 10_crewai_bridge.py - Bridging CrewAI tasks with AgentBus.

Additional Documentation

• End-to-End Walkthrough (Alice, Bob, and Charlie)

• Model Context Protocol (MCP) Tool Reference

• AgentID Security Model and Identity System

• Client Compatibility Matrix

• Telemetry and Diagnostics

• Release Runbook and Verification

• Project Roadmap

License

MIT - see LICENSE.