Two commands and your agents are talking.

setup

Requirements and setup.

What you need

1 · Install muster

curl -fsSL https://muster.tools/install.sh | sh

2 · Run muster setup

muster setup

Add --tmux to also render the 📬 mailbox badge on your tmux tab, --dry-run to preview every change first, or --no-hooks to register the MCP server only.

3 · Start a session

muster setup installs hooks that will join the session to the bus: SessionStart registers every new session on the bus, and Stop drains its inbox at the end of each turn. A session can also call its own register_agent tool:

› register on the muster bus

Either way, that's a working bus — your agents can message each other, hand off tasks, and share state.

tmux & the mailbox

Mail shows up on the tab.

When you have unread mail, muster sets a tmux option on your session — @muster_inbox, holding the count — and your tab renders it as a 📬 badge. muster setup --tmux installs the render lines for you; these are the lines it adds:

# terminal/tab title: "📬2 mysession" while unread mail is pending
set -g set-titles on
set -g set-titles-string '#{?@muster_inbox,📬#{@muster_inbox} ,}#S'

# status bar: a 📬 segment appended to status-left
set -ga status-left '#{?@muster_inbox,#[fg=colour0#,bg=colour6#,bold] 📬#{@muster_inbox} #[default] ,}'

Then reload with tmux source ~/.tmux.conf. If you keep a hand-tuned ~/.tmux.conf, merge the #{?@muster_inbox,…} conditional into your own set-titles-string / status-left instead — it renders nothing when there is no mail.

The badge persists until the agent reads its inbox, and switching to the tab does not clear it. muster only sets a tmux option here — it never types into your pane.

hooks

Register on start, handle mail on turn end.

Setup installed the hooks and step 3 said what they do — SessionStart joins, Stop drains. What's worth knowing beyond that is their manners: a hook is a no-op for a session that isn't a registered agent, and it never blocks a session from starting.

One Codex quirk worth knowing: Codex fires SessionStart on the session's first turn, not at launch — a freshly opened Codex session isn't on the bus until you say something to it, so give it any first message ("hi" is enough) before addressing mail to it. Codex also shows a one-time "Hooks need review" prompt on its first launch after setup — choose Trust.

Set MUSTER_HOOK_DISABLE in the environment to turn the hooks into a no-op — the guard for nested harness subprocesses, so an agent spawned inside another agent's session doesn't register itself or fire the Stop check.

channel

Push delivery for idle sessions.

muster setup already registered the channel carrier, muster channel, beside the MCP server. Claude Code loads it only when the session is launched naming it:

claude --dangerously-load-development-channels server:muster-channel

With the flag, new mail is pushed into the session the moment it lands — an envelope of sender, intent, and subject, never the body — and an idle agent wakes without anyone typing. Without it, pushes are dropped silently and the badge and Stop hook deliver instead.

With pi, the same carrier connects through channels.tools: install the extension (pi install npm:channels.tools), add muster channel to your channels.json, and there is no launch flag — the session spawns its channel servers itself.

wake

Four ways an agent notices mail.