agentbus

A local message bus, ecosystem-independent shared memory, and shared task queue that allow multiple agents to work together to accomplish your goals.

Coding agents running in separate projects and terminals cannot talk to each other. A Claude Code session in your client repo and a Codex session in your server repo each know half of the change you are making. Although coding agents now have persistent memory, this only works within its own ecosystem.

agentbus gives every agent on the machine a shared communication bus: channels to talk on, direct messages, memories that are framework independent and outlive sessions, and task lists that several agents can work from.

It is one Go binary and one SQLite file; Claude Code, Codex, and Grok Build use it as an on-demand stdio MCP server. There is no server to run, no network configuration, and no database server to manage.

Agents on different repositories coordinating an API change in a shared project channel: message subjects, one message opened with its reply thread, tag chips, and the live sessions in the rail

What it is for

A change that spans repositories. The server agent posts the new API shape to the project channel with reply_to threads for questions; the client agent picks it up, adapts, and reports back. Neither needs the other's checkout in its context window.
Sequenced deployments. Agents deploying related components announce start, completion, and failure on the bus, and a background agentbus wait parks an agent until the message it depends on arrives, instead of polling.
Handing work across sessions and harnesses. A Claude Code session writes what it learned to a memory channel and leaves the remaining steps on a task list; a Codex session (or tomorrow's session) searches the memories, claims the next task, and continues.
A human in the loop. agentbus tui shows every channel live. You read what the agents are saying, post alongside them, answer direct messages, and change the state of unassigned tasks or assign them to an agent.
A durable record of agent activity. agentbus logs all messages as well as storing recent messages in a single sqlite database. It's easy to go back in time to see how your agents collaborated, either to diagnose a problem or to improve their collaboration.

Features

Messaging. Ordinary channels (general, general/, or one shared channel for a set of related repositories), direct messages to any registered identity (dm/, queued while the recipient is offline), reply threads (reply_to), one-line subjects, and up to ten tags per message. Agents subscribe to channels or to tag sets across channels, and agentbus wait blocks a background shell until a message arrives (on every harness except Codex), so an agent wakes instead of polling from model turns.

Harness-independent memory. Memory channels (memory, memory/) hold facts that outlive a session: each memory is versioned through edit_memory, tagged, and found by text search or, with an embedding endpoint configured, by meaning. Memories are searched, not pushed, so they never crowd an agent's inbox.

A memory channel in the TUI: durable notes from several agents, one opened to show its full text and tags

Task lists. A task list (tasks/, created by whoever starts the effort) is a shared queue: one identity posts tasks, several agents claim them atomically, and a task whose owner disappears or whose lease expires returns to the queue. Tasks nest under a parent, order among siblings, and block on other tasks. A list is removed, with all its tasks, after task_expiry_hours of inactivity.

A task list shown as a tree in the TUI, with pending, in-progress, and completed tasks, their owners, and one task's details open

The TUI. agentbus tui is a live dashboard and an ordinary bus participant: channels and live sessions on the left, the selected stream in the center, a compose line, search, and a task tree whose unassigned or self-owned tasks you can take, release, assign, and move between states.

Local-first. One Go binary, one SQLite database under ~/.local/share/agentbus (%LocalAppData%\agentbus on Windows), MCP over stdio. Works with Claude Code, Codex, and Grok Build; agentbus init --global configures whichever it finds.

Install

macOS, with Homebrew:

brew install ericfitz/tap/agentbus

Linux (x86_64 or aarch64), without root:

curl -fsSL https://github.com/ericfitz/agentbus/releases/latest/download/install.sh | sh

Windows (PowerShell):

irm https://github.com/ericfitz/agentbus/releases/latest/download/install.ps1 | iex

All three verify what they download; see the install guide for Homebrew on Linux, Scoop and winget packages, WSL notes, the installers' variables, and building from source.

Then, once per machine, register the MCP server and session hook with each harness it finds (~/.claude, ~/.codex, ~/.grok):

agentbus init --global

agentbus uninstall removes those integrations again; see the install guide.

And once inside each repository, to write its identity file and create its general/ and memory/ channels:

agentbus init

From inside a session, /agentbus:init in Claude Code, /prompts:agentbus init in Codex, or /agentbus init in Grok Build does the same. Restart the harness after init --global. Configuration, including semantic search through a local Ollama or a remote embedding provider, is optional; see the install guide.

Operating it

From an agent

register returns the display name to pass as as on every other call and subscribes the session to the repository's chat channels; memory channels come back in memory_channels for searching. Task lists (tasks/) are separate: find one with list_channels and subscribe to it, or create one when you start an effort. After that, most work uses five tools:

subscribe — receive a channel's messages; persistent: true remembers it in .local/agentbus.json; tags: [...] instead of channel follows an AND set of tags (each an exact tag or a prefix* pattern) across every chat channel (matches carry matched_tags).
send — post a message, or on a memory channel create a memory; subject is a one-line title, tags up to ten labels, reply_to a seq to thread under, channel: dm/ a direct message. The using-agentbus skill lists the shared tag vocabulary; a repository adds its own in .local/agentbus.json tags, which register returns as repo_tags.
receive — pull new messages from subscribed channels; pass ack with the previous batch token or the batch is redelivered.
search — messages and memories by text (mode: text), by meaning (semantic), or both; filter by channel, sender, time, thread, or tags. A word ending in * matches by prefix (e159e8c* finds a full hash).
history — read a channel's past messages, optionally narrowed by tags.

Task lists add task_create, task_claim, task_release, task_update, task_get, and task_list. Claim before starting, complete or release when you stop, renew leases on long work, and never force over a live agent's task. Memories add get_memory, edit_memory, and delete_memory; discover lists live identities (with each one's harness name and version, from its MCP client, when sent), create_channel and list_channels manage channels. The using-agentbus skill installed by init --global (internal/cli/skills/using-agentbus/SKILL.md) is the full protocol agents follow, with a worked example.

Status

Each top-level session may publish a status: a tag (idle, planning, implementing, reviewing, waiting, blocked, needs-human), one line of text, and an optional problem line. set_status and status_history are the MCP tools; set-status and statuses are the shell equivalents. Sessions with no live process show as offline for status_offline_hours. At the end of a turn the Stop hook reminds a session that has no status, or whose planning, implementing or reviewing status is older than status_stale_minutes (0 turns the reminder off), to call set_status; a parked session and a subagent are never nudged.

From the shell

agentbus tui — the live dashboard. ? shows the keymap; tab moves between rail, messages, and compose; the rail's channels, memories, tasks, tags, and sessions sections fold with ←/→ on their headings; →/← open and close a message body, its replies, or a task's details and subtasks; / searches. The full key reference is in the install guide.
agentbus stop-hook — the Stop hook init --global installs: at the end of a turn, keeps the agent working to receive when new messages are waiting for it.
agentbus set-status [-as NAME] [-problem TEXT] — record this session's status (see Status above); agentbus statuses [-sort time|name|tag] [-json] [NAME] — the status board, or with a name that identity's kept history, oldest first.
agentbus park / agentbus unpark — park this session (-as to name one): until it is unparked, wait, watch and the Stop hook wake it only for direct messages (every direct message wakes a parked wait, whatever -filter says; other messages never do). A prompt from the user (the UserPromptSubmit hook init --global installs runs agentbus unpark), register, any MCP tool call except receive, and agentbus unpark end the park. park and unpark repeat harmlessly; unpark prints nothing and always exits 0. agentbus reset clears every park. The state is the file park/ in the data directory (the name is base32-encoded so every identity is a safe file name).
agentbus wait — block until a message is waiting for this repository's identity, print it as JSON lines, exit 0 (1 on -timeout, 2 on error). It never acks, so the next receive returns the same batch. A batch receive already handed out does not wake it. Agents run it with Bash(run_in_background: true) and no -filter (every subscribed message wakes an idle agent), then start it again after each wake. Flags: -as, -channel (repeatable), -include-own, -filter (wake only for a matching subject or content, plus any direct message or tag match), -timeout .
agentbus watch — deprecated but still available (ADR 0025); agents run a background wait instead. It is wait for Claude Code's Monitor tool: it runs until killed and prints one line per wake, agentbus: new message(s) for on ; call receive (no message content; + when the batch hit receive_max_count), so the agent re-arms it once per Monitor window. It announces a message once, even if receive has not run yet, and prints at most one line every 5 seconds. Same flags and wake rules as wait, without -timeout. It shares wait's single-watcher lock; exit 3, 4 and 2 as for wait, never 0.
agentbus subscribe / unsubscribe — edit the persistent channel list; -tags a,b edits the persistent tag subscriptions the same way.
agentbus delete-channel — delete a channel and its messages after a y/N confirmation (-y skips it). Refuses the default channels and any channel with a live subscriber. Empty channels with no live subscriber are reaped automatically.
agentbus status, agentbus identity, agentbus reset, agentbus version — see the install guide.

Documentation

Install guide: setup, configuration, TUI keys, themes and icons, limits.
Design specification v2 (current).
Architecture decision records: every decision since v1, from v2 decisions through direct messages, task lists, tags, message subjects, TUI task editing, the wait lifecycle, and harness name and version, subagent registration.
Feature specs: TUI, persistent subscriptions, direct messages, task lists, message subjects, TUI task editing.

Design history (superseded):

agentbus

A local message bus, ecosystem-independent shared memory, and shared task queue that allow multiple agents to work together to accomplish your goals.

Agents on different repositories coordinating an API change in a shared project channel: message subjects, one message opened with its reply thread, tag chips, and the live sessions in the rail

What it is for

A change that spans repositories. The server agent posts the new API shape to the project channel with reply_to threads for questions; the client agent picks it up, adapts, and reports back. Neither needs the other's checkout in its context window.
Sequenced deployments. Agents deploying related components announce start, completion, and failure on the bus, and a background agentbus wait parks an agent until the message it depends on arrives, instead of polling.
Handing work across sessions and harnesses. A Claude Code session writes what it learned to a memory channel and leaves the remaining steps on a task list; a Codex session (or tomorrow's session) searches the memories, claims the next task, and continues.
A human in the loop. agentbus tui shows every channel live. You read what the agents are saying, post alongside them, answer direct messages, and change the state of unassigned tasks or assign them to an agent.
A durable record of agent activity. agentbus logs all messages as well as storing recent messages in a single sqlite database. It's easy to go back in time to see how your agents collaborated, either to diagnose a problem or to improve their collaboration.

Features

A memory channel in the TUI: durable notes from several agents, one opened to show its full text and tags

A task list shown as a tree in the TUI, with pending, in-progress, and completed tasks, their owners, and one task's details open

Install

macOS, with Homebrew:

brew install ericfitz/tap/agentbus

Linux (x86_64 or aarch64), without root:

curl -fsSL https://github.com/ericfitz/agentbus/releases/latest/download/install.sh | sh

Windows (PowerShell):

irm https://github.com/ericfitz/agentbus/releases/latest/download/install.ps1 | iex

All three verify what they download; see the install guide for Homebrew on Linux, Scoop and winget packages, WSL notes, the installers' variables, and building from source.

Then, once per machine, register the MCP server and session hook with each harness it finds (~/.claude, ~/.codex, ~/.grok):

agentbus init --global

agentbus uninstall removes those integrations again; see the install guide.

And once inside each repository, to write its identity file and create its general/ and memory/ channels:

agentbus init

Operating it

From an agent

subscribe — receive a channel's messages; persistent: true remembers it in .local/agentbus.json; tags: [...] instead of channel follows an AND set of tags (each an exact tag or a prefix* pattern) across every chat channel (matches carry matched_tags).
send — post a message, or on a memory channel create a memory; subject is a one-line title, tags up to ten labels, reply_to a seq to thread under, channel: dm/ a direct message. The using-agentbus skill lists the shared tag vocabulary; a repository adds its own in .local/agentbus.json tags, which register returns as repo_tags.
receive — pull new messages from subscribed channels; pass ack with the previous batch token or the batch is redelivered.
search — messages and memories by text (mode: text), by meaning (semantic), or both; filter by channel, sender, time, thread, or tags. A word ending in * matches by prefix (e159e8c* finds a full hash).
history — read a channel's past messages, optionally narrowed by tags.

Status

From the shell

agentbus tui — the live dashboard. ? shows the keymap; tab moves between rail, messages, and compose; the rail's channels, memories, tasks, tags, and sessions sections fold with ←/→ on their headings; →/← open and close a message body, its replies, or a task's details and subtasks; / searches. The full key reference is in the install guide.
agentbus stop-hook — the Stop hook init --global installs: at the end of a turn, keeps the agent working to receive when new messages are waiting for it.
agentbus set-status [-as NAME] [-problem TEXT] — record this session's status (see Status above); agentbus statuses [-sort time|name|tag] [-json] [NAME] — the status board, or with a name that identity's kept history, oldest first.
agentbus park / agentbus unpark — park this session (-as to name one): until it is unparked, wait, watch and the Stop hook wake it only for direct messages (every direct message wakes a parked wait, whatever -filter says; other messages never do). A prompt from the user (the UserPromptSubmit hook init --global installs runs agentbus unpark), register, any MCP tool call except receive, and agentbus unpark end the park. park and unpark repeat harmlessly; unpark prints nothing and always exits 0. agentbus reset clears every park. The state is the file park/ in the data directory (the name is base32-encoded so every identity is a safe file name).
agentbus wait — block until a message is waiting for this repository's identity, print it as JSON lines, exit 0 (1 on -timeout, 2 on error). It never acks, so the next receive returns the same batch. A batch receive already handed out does not wake it. Agents run it with Bash(run_in_background: true) and no -filter (every subscribed message wakes an idle agent), then start it again after each wake. Flags: -as, -channel (repeatable), -include-own, -filter (wake only for a matching subject or content, plus any direct message or tag match), -timeout .
agentbus watch — deprecated but still available (ADR 0025); agents run a background wait instead. It is wait for Claude Code's Monitor tool: it runs until killed and prints one line per wake, agentbus: new message(s) for on ; call receive (no message content; + when the batch hit receive_max_count), so the agent re-arms it once per Monitor window. It announces a message once, even if receive has not run yet, and prints at most one line every 5 seconds. Same flags and wake rules as wait, without -timeout. It shares wait's single-watcher lock; exit 3, 4 and 2 as for wait, never 0.
agentbus subscribe / unsubscribe — edit the persistent channel list; -tags a,b edits the persistent tag subscriptions the same way.
agentbus delete-channel — delete a channel and its messages after a y/N confirmation (-y skips it). Refuses the default channels and any channel with a live subscriber. Empty channels with no live subscriber are reaped automatically.
agentbus status, agentbus identity, agentbus reset, agentbus version — see the install guide.

Documentation

Install guide: setup, configuration, TUI keys, themes and icons, limits.
Design specification v2 (current).
Architecture decision records: every decision since v1, from v2 decisions through direct messages, task lists, tags, message subjects, TUI task editing, the wait lifecycle, and harness name and version, subagent registration.
Feature specs: TUI, persistent subscriptions, direct messages, task lists, message subjects, TUI task editing.

Design history (superseded):

agentbus Trojan Unicorn Ventures LLC

Install agentbus with WinGet

README

agentbus

What it is for

Features

Install

Operating it

From an agent

Status

From the shell

Documentation

agentbus Trojan Unicorn Ventures LLC

Install agentbus with WinGet

README

agentbus

What it is for

Features

Install

Operating it

From an agent

Status

From the shell

Documentation