AgentBus

The SQLite-Backed MCP Event Bus & Control Surface for Heterogeneous Agent Swarms.

When Cursor, Claude, Antigravity, and Terminal Agents (like Hermes) share a workspace, they usually coordinate through fragile append-only files (log.md). That works until you need SLA timeouts, Human-in-the-Loop (HITL) intercepts, strict schema validation, or cryptographic RBAC.

AgentBus replaces the "Game of Telephone" with a localhost sidecar: a Python MCP server backed by SQLite. No orchestrator runtime lock-in. No heavy cloud dashboard. Just a hyper-fast local pub/sub built for top-tier AI orchestration.

v0.19.0 (August 2026): Release-integrity gates, honest runtime diagnostics, registered Codex/Pi headless adapters, and untrusted-event prompt containment, on top of the MCP Python SDK v2 migration. See the changelog for details.

Note: Install as okf-agentbus (CLI command remains agentbus). Extras: [obs,devex,jupyter,sdk].

⚡ The "Ah-Ha" Moment: Zero-Restart Integration

Already running Aider, OpenHands, or custom agents in tmux panes? Do not kill your sessions. AgentBus features a dual-interface architecture (MCP + CLI). You don't need to wire up JSON configs to test it today. Just prompt your running agent:

"Use your terminal to run agentbus publish --topic okf/handoff --payload '{\"from\":\"grok\",\"to\":\"hermes\",\"summary\":\"Write tests\"}'"

The SQLite bus instantly captures it, without requiring the MCP server. Once you're convinced by the Mission Control TUI, you can wire up the strongly-typed MCP server for your next boot.

Why AgentBus?

Alternative	Limitation	AgentBus
`log.md` blackboard	No schema, race conditions	Typed topics, monotonic IDs, advisory locks
LangGraph / CrewAI	Same-runtime lock-in	Heterogeneous out-of-process clients (IDE + CLI)
LangSmith	Cloud-only, backward-looking	Local SQLite, forward-looking Execution TUI
Redis pub/sub	Extra daemon, complex setup	Zero-config SQLite, native stdio MCP

Feature Arsenal (v0.3 - v0.18)

MCP Python SDK v2 (v0.18): migrated the stdio MCP server while preserving the existing event-store contract.
Resilient delivery (v0.16.4): bounded retry with jitter, retry-exhausted dead letters and file spillover for SQLite contention.
Async suspend/resume (v0.16): durable waits and correlated wake events let headless agents yield without busy polling.
Headless runners (v0.15): opt-in adapters for heterogeneous CLI agents with bounded chain behavior and structured acknowledgements.
Wake plane and Go helpers (v0.12-v0.13): platform-packaged workers, role leases, wake ingress and webhook delivery.
Jupyter async client (v0.11): from agentbus.jupyter import AsyncAgentBus + %agentbus start — non-blocking polls that yield to the notebook event loop.
TypeScript client (v0.11): packages/js/agentbus-client — Node EventEmitter + MCP stdio spawn (@agentbus/agentbus-client, path install for now).
God View Mesh (v0.9): Passive OS + MCP observability so silent agents still leave bus footprints (system/mcp, system/fs, system/shell, system/monologue).
Mission Control TUI (v0.8+): A rich, keyboard-driven Textual dashboard (agentbus monitor). Trace waterfall, HITL, Wiretap pane, Dark Agent warnings.
Pluggable Pydantic Schemas (v0.7): Code-first @bus.topic decorators to enforce strict JSON schemas at the insertion layer.
Distributed Context (v0.6): Pass massive context (like git diffs) via --attach. Hard 1MB payload limits prevent context window explosion.
Agentic Observability (v0.5): Native OpenTelemetry-style trace_id and parent_span_id lineage.
SLA Timeouts & Dead-Letter (v0.4): Prevent phantom deadlocks. If an agent ghosts the swarm, SLA timers route the payload to okf/dead-letter.
Swarm RBAC & Droid Proofs (v0.3): Cryptographic JWT/UUID tokens ensure only authorized agents can publish to restricted topics.
HITL Intercepts (v0.3): Catch dangerous payloads (e.g., DROP TABLE) and place them in PENDING_APPROVAL for human review via the TUI.

Install

The fastest way (Installs & Auto-wires your IDEs in one step):

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

Or manually via pip:

pip install -U "okf-agentbus[devex,sdk]"
agentbus init --apply --producer-id my-agent

Jupyter notebooks:

pip install -U "okf-agentbus[jupyter]"

%load_ext agentbus.jupyter
%agentbus start
# or
from agentbus.jupyter import AsyncAgentBus
bus = AsyncAgentBus()  # AGENTBUS_WORKSPACE or cwd
bus.on_event(print)
await bus.start_background(interval=1.0)

TypeScript (from monorepo checkout):

cd packages/js/agentbus-client && npm install && npm test
# set AGENTBUS_WORKSPACE + agentbus on PATH, then use createStdioMcpClient / AgentBus

Quickstart & Examples

The best way to understand AgentBus is to read our copy-pasteable examples.

See the examples/ directory for 7 flawless, isolated Python scripts covering every feature from basic Pub/Sub to Pydantic Schemas and SLA Timeouts.

# Terminal A — Launch the Mission Control TUI
agentbus monitor

# Terminal B — Publish a handoff
agentbus publish \
  --topic okf/handoff \
  --payload '{"from":"cursor","to":"hermes","summary":"Write tests"}'

Before operating or releasing a workspace, run the read-only diagnostics:

agentbus doctor --workspace /path/to/workspace
agentbus doctor --workspace /path/to/workspace --json

The command inspects the target without publishing to its bus. Write-path and MCP stdio checks run in temporary isolated workspaces. --strict makes warnings (including absent optional Go helpers) fail CI.

God View Observability (v0.9.0):

Track silent agents by wiretapping their operations:

# Intercept MCP tool calls
mcp-serve --wiretap

# Watch file edits and command executions
agentbus watch

# Tail internal agent reasoning logs
agentbus tail

Events will stream into the TUI's Wiretap pane as system/mcp, system/fs, system/shell, and system/monologue topics.

📦 Workspace Isolation (The `.agentbus` directory)

AgentBus operates on the concept of Workspace Isolation (similar to how git uses .git or Docker uses docker-compose.yml).

The bus and its events are physically scoped to the directory you run it in. This prevents your Swarm from tracking your entire operating system or cross-contaminating different projects.

When you navigate to a specific project folder and run agentbus init or agentbus up, it creates a localized .agentbus/events.db SQLite database specifically for that directory.

1-Click Swarm Orchestration (v0.10.0)

Instead of manually opening 5 tmux panes to start your agents and observability daemons, use the new orchestrator:

cd /path/to/my-project

# 1. Generate a boilerplate .agentbus/swarm.yaml
agentbus up --init

# 2. Boot the swarm (Watchers, Agents, and TUI) in one click
agentbus up

# 3. View running background agents
agentbus ps

# 4. Safely kill the entire swarm
agentbus down

Documentation

For full architectural documentation, see the docs/ directory.

License

MIT — see LICENSE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

okf_agentbus-0.19.0.tar.gz (232.8 kB view details)

Uploaded Aug 23, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

okf_agentbus-0.19.0-py3-none-win_amd64.whl (7.2 MB view details)

Uploaded Aug 23, 2026 Python 3Windows x86-64

okf_agentbus-0.19.0-py3-none-manylinux2014_x86_64.whl (7.0 MB view details)

Uploaded Aug 23, 2026 Python 3

okf_agentbus-0.19.0-py3-none-manylinux2014_aarch64.whl (6.4 MB view details)

Uploaded Aug 23, 2026 Python 3

okf_agentbus-0.19.0-py3-none-macosx_11_0_x86_64.whl (7.1 MB view details)

Uploaded Aug 23, 2026 Python 3macOS 11.0+ x86-64

okf_agentbus-0.19.0-py3-none-macosx_11_0_arm64.whl (6.7 MB view details)

Uploaded Aug 23, 2026 Python 3macOS 11.0+ ARM64

File details

Details for the file okf_agentbus-0.19.0.tar.gz.

File metadata

Download URL: okf_agentbus-0.19.0.tar.gz
Upload date: Aug 23, 2026
Size: 232.8 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for okf_agentbus-0.19.0.tar.gz
Algorithm	Hash digest
SHA256	`8ba5826f89536ea770e75deffab6a4b3efb5fb6991971531434b46b6d1b6faa3`
MD5	`8b13ac1770eea482a0a0db9d521120b3`
BLAKE2b-256	`d1928aeba967eb2641bcd85d5a39b8642dbedd37956d1a0cdaae22803c8f9ad6`

See more details on using hashes here.

Provenance

The following attestation bundles were made for okf_agentbus-0.19.0.tar.gz:

Publisher: release.yml on onicarps/agentbus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: okf_agentbus-0.19.0.tar.gz
- Subject digest: 8ba5826f89536ea770e75deffab6a4b3efb5fb6991971531434b46b6d1b6faa3
- Sigstore transparency entry: 2572326064
- Sigstore integration time: Aug 23, 2026
Source repository:
- Permalink: onicarps/agentbus@14d58726f6a9ffe67a6f46b2a0429239a128feab
- Branch / Tag: refs/tags/v0.19.0
- Owner: https://github.com/onicarps
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@14d58726f6a9ffe67a6f46b2a0429239a128feab
- Trigger Event: push

File details

Details for the file okf_agentbus-0.19.0-py3-none-win_amd64.whl.

File metadata

Download URL: okf_agentbus-0.19.0-py3-none-win_amd64.whl
Upload date: Aug 23, 2026
Size: 7.2 MB
Tags: Python 3, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for okf_agentbus-0.19.0-py3-none-win_amd64.whl
Algorithm	Hash digest
SHA256	`647c82f6b835222e4d262d94b9271f124f933193c4b4dcce8b7f2ba5e54b8f57`
MD5	`2a4e72cd6e5151b5dfd0a463516fe9e7`
BLAKE2b-256	`5d42ea7167d56bcbd3bddad734d78652e7b9bd5bd6ee2f90a4dae558a5f85b92`

See more details on using hashes here.

Provenance

The following attestation bundles were made for okf_agentbus-0.19.0-py3-none-win_amd64.whl:

Publisher: release.yml on onicarps/agentbus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: okf_agentbus-0.19.0-py3-none-win_amd64.whl
- Subject digest: 647c82f6b835222e4d262d94b9271f124f933193c4b4dcce8b7f2ba5e54b8f57
- Sigstore transparency entry: 2572327073
- Sigstore integration time: Aug 23, 2026
Source repository:
- Permalink: onicarps/agentbus@14d58726f6a9ffe67a6f46b2a0429239a128feab
- Branch / Tag: refs/tags/v0.19.0
- Owner: https://github.com/onicarps
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@14d58726f6a9ffe67a6f46b2a0429239a128feab
- Trigger Event: push

File details

Details for the file okf_agentbus-0.19.0-py3-none-manylinux2014_x86_64.whl.

File metadata

Download URL: okf_agentbus-0.19.0-py3-none-manylinux2014_x86_64.whl
Upload date: Aug 23, 2026
Size: 7.0 MB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for okf_agentbus-0.19.0-py3-none-manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`f4c5f1755c864e85938c0915dfe347376ebf4b57fcbd55d91116a52067baf8d7`
MD5	`1a9758809286ece29d2860fdfde1c42e`
BLAKE2b-256	`b3dd46bc74a65d56145783e9e5bd5715aa05149c3769bcb1894c29cb46bbad6c`

See more details on using hashes here.

Provenance

The following attestation bundles were made for okf_agentbus-0.19.0-py3-none-manylinux2014_x86_64.whl:

Publisher: release.yml on onicarps/agentbus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: okf_agentbus-0.19.0-py3-none-manylinux2014_x86_64.whl
- Subject digest: f4c5f1755c864e85938c0915dfe347376ebf4b57fcbd55d91116a52067baf8d7
- Sigstore transparency entry: 2572326298
- Sigstore integration time: Aug 23, 2026
Source repository:
- Permalink: onicarps/agentbus@14d58726f6a9ffe67a6f46b2a0429239a128feab
- Branch / Tag: refs/tags/v0.19.0
- Owner: https://github.com/onicarps
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@14d58726f6a9ffe67a6f46b2a0429239a128feab
- Trigger Event: push

File details

Details for the file okf_agentbus-0.19.0-py3-none-manylinux2014_aarch64.whl.

File metadata

Download URL: okf_agentbus-0.19.0-py3-none-manylinux2014_aarch64.whl
Upload date: Aug 23, 2026
Size: 6.4 MB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for okf_agentbus-0.19.0-py3-none-manylinux2014_aarch64.whl
Algorithm	Hash digest
SHA256	`950b49bf9746eaded3f6d1bbac3f013d412ee690c9af744b389d5d16d1baf63c`
MD5	`975fe0b77788e13572f7af03784c8fc9`
BLAKE2b-256	`49aea3574da16c7e75a44fda8fb04f2afdf7861452c7678c87afcd7f62f50052`

See more details on using hashes here.

Provenance

The following attestation bundles were made for okf_agentbus-0.19.0-py3-none-manylinux2014_aarch64.whl:

Publisher: release.yml on onicarps/agentbus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: okf_agentbus-0.19.0-py3-none-manylinux2014_aarch64.whl
- Subject digest: 950b49bf9746eaded3f6d1bbac3f013d412ee690c9af744b389d5d16d1baf63c
- Sigstore transparency entry: 2572326598
- Sigstore integration time: Aug 23, 2026
Source repository:
- Permalink: onicarps/agentbus@14d58726f6a9ffe67a6f46b2a0429239a128feab
- Branch / Tag: refs/tags/v0.19.0
- Owner: https://github.com/onicarps
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@14d58726f6a9ffe67a6f46b2a0429239a128feab
- Trigger Event: push

File details

Details for the file okf_agentbus-0.19.0-py3-none-macosx_11_0_x86_64.whl.

File metadata

Download URL: okf_agentbus-0.19.0-py3-none-macosx_11_0_x86_64.whl
Upload date: Aug 23, 2026
Size: 7.1 MB
Tags: Python 3, macOS 11.0+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for okf_agentbus-0.19.0-py3-none-macosx_11_0_x86_64.whl
Algorithm	Hash digest
SHA256	`b0afec21aa4e3e373268f0fc4f6f770534f3d71f41b9663f946c0f6ef1df2016`
MD5	`231454001f0d6464a2947a1e65076a42`
BLAKE2b-256	`8dacfe275613334085d5c1658f19d19bf249c447c5a4a568b37e5c8e60d046e4`

See more details on using hashes here.

Provenance

The following attestation bundles were made for okf_agentbus-0.19.0-py3-none-macosx_11_0_x86_64.whl:

Publisher: release.yml on onicarps/agentbus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: okf_agentbus-0.19.0-py3-none-macosx_11_0_x86_64.whl
- Subject digest: b0afec21aa4e3e373268f0fc4f6f770534f3d71f41b9663f946c0f6ef1df2016
- Sigstore transparency entry: 2572326837
- Sigstore integration time: Aug 23, 2026
Source repository:
- Permalink: onicarps/agentbus@14d58726f6a9ffe67a6f46b2a0429239a128feab
- Branch / Tag: refs/tags/v0.19.0
- Owner: https://github.com/onicarps
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@14d58726f6a9ffe67a6f46b2a0429239a128feab
- Trigger Event: push

File details

Details for the file okf_agentbus-0.19.0-py3-none-macosx_11_0_arm64.whl.

File metadata

Download URL: okf_agentbus-0.19.0-py3-none-macosx_11_0_arm64.whl
Upload date: Aug 23, 2026
Size: 6.7 MB
Tags: Python 3, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for okf_agentbus-0.19.0-py3-none-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`be6a6614dd0f7c6150b492c2483da8c1b21f805c2cf497e2ddb792f88128dacd`
MD5	`8e75870d8ca8627cc71b403eac7696eb`
BLAKE2b-256	`96529f158148f711779d6ac86ab00cdeec219125e40d9fbad3be5fd46165ab82`

See more details on using hashes here.

Provenance

The following attestation bundles were made for okf_agentbus-0.19.0-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on onicarps/agentbus

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: okf_agentbus-0.19.0-py3-none-macosx_11_0_arm64.whl
- Subject digest: be6a6614dd0f7c6150b492c2483da8c1b21f805c2cf497e2ddb792f88128dacd
- Sigstore transparency entry: 2572327473
- Sigstore integration time: Aug 23, 2026
Source repository:
- Permalink: onicarps/agentbus@14d58726f6a9ffe67a6f46b2a0429239a128feab
- Branch / Tag: refs/tags/v0.19.0
- Owner: https://github.com/onicarps
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@14d58726f6a9ffe67a6f46b2a0429239a128feab
- Trigger Event: push