● muster
local · MIT  

Reference

The full command reference, the mailbox, hooks, and wake.

This is the lookup page: every CLI command with its signature and flags, how the tmux mailbox is wired, the session-lifecycle hooks, and the three ways an agent notices mail. For the pitch and the message-flow walkthrough, see the landing page.

the cli

Every command, from any shell.

Agents coordinate over the MCP tools described on the landing page. The CLI is the same bus, for humans and for hooks — every operation the daemon supports is reachable from a plain subcommand, not just the eleven MCP tools.

muster serve Runs the daemon in the foreground. You don't normally start it yourself — the CLI and the MCP server both spawn it automatically the first time anything touches the bus — so run this by hand only when you want to watch its log.
muster mcp Serves the bus over stdio as an MCP server. This is the command each agent registers with its MCP client, and the source of the eleven coordination tools.
muster station Opens the full-screen operator TUI described in the station section on the landing page — projects, agents, threads, and the conversation, with send, reply, and nudge built in.
muster agents Prints the roster: every registered agent's project, alias, label, model, and whether its tmux session is currently live.
muster inbox <target> Prints one agent's threads — everything addressed to it or started by it, with kind, status, and unread count. muster tasks <target> prints the same inbox filtered down to threads that are tasks.
muster thread <id> Prints one thread in full — the header (kind, participants, status, intent, subject), then every entry oldest-first with its author, timestamp, and verbatim body. Reading a thread this way never marks it read; muster inbox owns the read watermark.
muster reply <thread-id> "…" --from <alias> Appends a reply to an existing thread and flags every participant's mailbox, exactly as the MCP reply tool would. With inbox and thread, this completes the read-and-respond loop from a plain shell — the same loop the MCP tools provide, for sessions (or humans) without an MCP connection.
muster send <target> "…" --from <alias> Sends a message. --intent fyi|reply-requested|action-requested tags what kind of response it expects, --subject and --ref attach a subject line and a pointer to the work, --role treats the target as a role rather than an alias, and --broadcast sends to everyone instead of one target.
muster nudge <target> [--no-submit] Wakes an idle agent right now by typing "check your inbox" into its tmux pane and pressing Enter — this is the only muster command that ever types into a pane. --no-submit types the line without pressing Enter, so you can edit it first.
muster label <name> Pins an addressable name on the current tmux session, so send <name> "…" reaches it from then on. muster label --clear removes it. Both require running inside tmux.
muster register [alias] / muster deregister [alias] Join or leave the bus by hand — the alias defaults to the current tmux session's name if you don't pass one. register also takes --role <role> and --model <claude|codex>. Session hooks call both of these for you; see below.
muster device [<name>] Shows this machine's device name, or sets it. The name appears in the roster's DEVICE column on a bus spanning machines, so an agent can resolve "the ci-cd session on my work laptop" to an alias — and it seeds derived aliases, so two machines with the same repos checked out cannot claim the same one. Only relevant with the hosted backend.
muster gc [--purge-agents] [--events-keep <dur>] Tombstones every agent whose tmux session is gone — soft-deleted, kept as history — and prunes journal rows older than --events-keep (default 720h). --purge-agents hard-deletes departed or dead agent rows instead of tombstoning them; that step is irreversible.
muster events [--agent] [--kind] [--thread] [--limit] Prints the bus journal after the fact — every send, reply, task change, nudge, and mailbox notify, newest activity last. Any of the filters can narrow it to one agent, one event kind, or one thread.
muster watch The same journal as muster events, but live: prints recent backlog, then follows the bus and prints each new event as it happens until you interrupt it. Takes the same --agent/--kind/--thread filters plus --interval for the poll rate.
muster hook <event> <model> The binary acting as its own session hook, wired into your agent harness's lifecycle config. SessionStart registers the session, Stop checks for unread mail at the end of a turn and tells the agent to go read it, and SessionEnd deregisters. See the hooks section for the exact config.
muster debug <op> [key=value …] Sends one raw daemon operation with string key=value arguments and prints the raw JSON response — the escape hatch behind the claim above: every daemon operation is reachable from the CLI, including ones with no dedicated subcommand.

tmux & the mailbox

Mail shows up on the tab.

When mail arrives, the daemon sets a tmux option on the recipient's session — @muster_inbox, holding the unread count. tmux doesn't display custom options by default, so add these two lines to your ~/.tmux.conf and reload (tmux source ~/.tmux.conf):

# render the muster mailbox in the tab title and status bar
set -g set-titles on
set -g set-titles-string '#{?@muster_inbox,📬#{@muster_inbox} ,}#S'
set -ga status-left '#{?@muster_inbox,#[fg=colour0#,bg=colour6#,bold] 📬#{@muster_inbox} #[default] ,}'

If you already customize set-titles-string or status-left, merge the #{?@muster_inbox,…} conditional into your own strings — it renders nothing when there is no mail.

web · frontend 📬 2 · api-2 · backend db · migrations

The flag persists until the agent reads its inbox (a get_inbox call clears it), and switching to the tab does not clear it. muster only sets a tmux option here; it never types into a pane. muster watch follows this same activity live from any shell, printing each message and inbox read as it happens.

hooks

Register on start, handle mail on turn end.

The muster binary is its own session hook: muster hook <event> <model>. Wired into your agent's lifecycle hooks, it does two things — SessionStart registers the session on the bus, and Stop (the end of each turn) checks for unread muster mail and, if there is any, instructs the agent to read its inbox and reply. There is nothing to copy or chmod, the hook is a no-op for sessions that aren't registered agents, and it never blocks a session from starting.

Claude Code — add to ~/.claude/settings.json

"hooks": {
  "SessionStart": [
    { "matcher": "startup|resume",
      "hooks": [ { "type": "command", "command": "muster hook SessionStart claude" } ] }
  ],
  "Stop": [
    { "hooks": [ { "type": "command", "command": "muster hook Stop claude" } ] }
  ],
  "SessionEnd": [
    { "hooks": [ { "type": "command", "command": "muster hook SessionEnd claude" } ] }
  ]
}

Codex — save as ~/.codex/hooks.json

{
  "hooks": {
    "SessionStart": [ { "hooks": [ { "type": "command", "command": "muster hook SessionStart codex" } ] } ],
    "Stop":         [ { "hooks": [ { "type": "command", "command": "muster hook Stop codex" } ] } ]
  }
}

Three Codex specifics: on the next codex launch it shows a one-time "Hooks need review" prompt — choose Trust (trust is recorded against the file's hash; editing it re-prompts). Codex fires SessionStart on the session's first turn, not at launch — a freshly opened Codex session is not on the bus until you say something to it, so give it any first message ("hi" is enough) before addressing mail to it. And Codex has no SessionEnd event — muster gc reaps agents whose tmux session is gone, so the roster stays honest either way.

If muster isn't on the PATH your harness gives hook commands (e.g. it's in ~/go/bin), use the absolute binary path in the command strings — Codex in particular does not expand ~.

wake

Three ways an agent notices mail.

mailbox The 📬 count on the tab — the notify steps of the flow. You see it, and the agent acts on it the next time it checks its inbox, or when you ask it to.
nudge muster nudge api-2 is the manual poke for waking an idle agent right now: it types "check your inbox" into that agent's pane and submits it.
stop hook The automatic path — the wake through reply steps of the flow. With the muster hook Stop entry from the hooks section above installed, an agent that finishes a turn with unread mail reads its inbox and replies on its own.