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.

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/<repo>, or one shared
channel for a set of related repositories), direct messages to any registered
identity (dm/<name>, 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/<repo>)
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.

Task lists. A task list (tasks/<effort>, 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.

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

And once inside each repository, to write its identity file and create its
general/<repo> and memory/<repo> 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/<effort>)
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/<name> 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.

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 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/<encoded name> 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 <regexp> (wake
  only for a matching subject or content, plus any direct message or tag
  match), -timeout <duration>.
• 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: <n> new message(s) for <name> on <channels>; call receive (no message content; <n>+ 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 <channel> / unsubscribe <channel> — edit the
  persistent channel list; -tags a,b edits the persistent tag
  subscriptions the same way.
• agentbus delete-channel <name> — 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):

• Review of v1 with harness verification
• Design specification v1
• v1 configuration
• v1 decisions