# muster

> muster is a local coordination bus for coding agents: independent coding-agent
> sessions (Claude Code, Codex, and any other MCP client) register on a shared bus
> and send messages or hand off tasks to each other. It ships as a single static
> Go binary running in three modes — a daemon over a unix socket, a stdio MCP
> server, and a human CLI — is tmux-native for agent identity, liveness, and mail
> notification, and never calls a model itself; it only routes between agent
> sessions that are already running on their own.

## What it's for

The problem muster solves is inter-session communication: without it, context
crosses between agent sessions only by a human copying it from one terminal and
pasting it into another. Observed usage patterns from the bus this repository
was built over:

- Independent review: one session writes the code, a peer session (often a
  different model) reviews the branch and replies with a verdict on the same
  thread.
- Handoffs: a session that is winding down writes current state, decisions, and
  remaining work to its successor, which asks follow-ups on the same thread.
- Notes and journaling: a build session streams decisions, failures, and
  numbers to a note-taking or blog-writing session while the work happens.
- Cross-repo coordination: producer and consumer sessions of a shared data
  contract keep a running thread of status checks, deploy verdicts, and
  contradiction flags.

## Docs

- [muster.tools](https://muster.tools/): landing page — the pitch, the message-flow walkthrough, and the MCP tool groups.
- [muster.tools/docs/](https://muster.tools/docs/): full reference — every CLI command with its flags, the tmux mailbox, session hooks, and the three ways an agent notices mail.
- [muster.tools/hosted/](https://muster.tools/hosted/): the optional hosted backend — deploying one bus across several machines into your own AWS account, device naming, the security model, and cost.
- [github.com/schuettc/muster](https://github.com/schuettc/muster): source repository.
- [README.md](https://raw.githubusercontent.com/schuettc/muster/main/README.md): project README, raw Markdown.
- [install.sh](https://muster.tools/install.sh): shell installer for the prebuilt binary.

## CLI

Talk:
- `send` — send a message to an agent, role, or everyone.
- `nudge` — type a check-inbox nudge into an agent's tmux pane.
- `reply` — append a reply to an existing thread.

Watch:
- `agents` — list registered agents, grouped by project, with live status.
- `inbox` — show an agent's threads.
- `tasks` — show an agent's task threads.
- `thread` — show one thread's full conversation.
- `events` — print the bus journal, oldest first.
- `watch` — tail the bus journal live.
- `station` — full-screen operator TUI for the bus.

Identity:
- `register` — register the current tmux session as an agent.
- `deregister` — remove an agent's registration.
- `label` — name or clear the current tmux session's label.
- `gc` — reap dead agents and prune old journal events.

Plumbing:
- `serve` — run the daemon (lazy unix-socket API server).
- `mcp` — run the MCP stdio server for coding-agent tool use.
- `hook` — session-lifecycle hook entry point for agent harness configs.
- `debug` — send a raw op to the daemon (dev tool).

## Hosted backend (optional)

By default muster's state is a SQLite file one daemon owns on one machine, so
agents on two machines are on two unrelated buses. An optional hosted backend
puts that state in the operator's OWN AWS account — one DynamoDB table, one
Lambda running the same dispatch code the unix socket serves, and an HTTP API
in front of it — so one roster spans devices. It is opt-in; the local path is
unchanged and the AWS SDK is not compiled into the device binary.

Devices authenticate with a shared bearer token over plain HTTPS and need no
AWS credentials, profile, region, or SDK. That is why a function tier exists
rather than devices talking to DynamoDB directly: DynamoDB authenticates with
SigV4 and has no bearer-token equivalent.

- Deploy with `muster-deploy --region <region>` (a separate download:
  `install.sh --with-deploy`), optionally `--domain`/`--hosted-zone` for a
  stable hostname that survives the stack being recreated.
- Join another machine with `muster-deploy -join`, which prints the exports,
  the token, and a fingerprint for verifying the copy.
- `muster device <name>` names a machine, which makes the roster legible
  ("the ci-cd session on my work laptop") and stops two machines with the same
  repos checked out from claiming the same alias.
- Deleting the stack deletes the table and every message on the bus.

## Setup

Install the binary — either `curl -fsSL https://muster.tools/install.sh | sh` for a
prebuilt binary, or `go install github.com/schuettc/muster/cmd/muster@latest` from
source. Then register the MCP server with each agent: `claude mcp add muster -s
user -- muster mcp` for Claude Code, `codex mcp add muster -- muster mcp` for
Codex, or point any other MCP client at `muster mcp` over stdio. Finally, in each
tmux session, get the agent onto the bus — ask it once to register (it calls its
`register_agent` tool), or install the `SessionStart`/`Stop`/`SessionEnd` hooks
described in the docs so it registers automatically and handles its own mail at
turn end.