@brutalsystems/muster weekly downloads statistics

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/muster-logo-dark.png"> <img src="docs/assets/muster-logo.png" alt="" width="132"> </picture>

Muster

Launch coding agents on your machine, under containment you chose, and get back an address you can actually reach.

Muster starts Claude Code, Codex and OpenCode sessions on your behalf. You say what the agent may do; Muster arranges it, verifies the session is genuinely alive, and hands you a durable address for it. If a session never becomes reachable, you get a diagnosis naming what stopped it — not a process that looks fine and isn't.

It is the launching half of a small family: Muster starts agents, tincan lets them message each other, birddog watches what they do.

What it's for

Running more than one agent, deliberately. One session reviewing while another builds; a task that runs once and captures its output; an agent launched under a separate account so its work never touches your own configuration. Muster is the part that makes those launches repeatable, contained and addressable instead of a terminal tab you have to remember.

A session returns an address only after its runtime is reachable. A task runs once, captures output, and never advertises a peer address.

What makes it different

• Containment is two separate questions, and both are answered. Whether the agent stops to ask you, and what it may touch — the second enforced by the OS, not by asking nicely. Every launch records which of the two it actually got.
• A session is only reported ready when it is reachable. Muster asks each runtime in its own language — a session record, an RPC call, an HTTP endpoint — and does not confuse "the process started" with "the agent is listening".
• It refuses instead of guessing. An unrecognised flag, a contradictory pair of options, an identity belonging to a different runtime: all errors, before anything is started. Nothing half-launched is left behind.
• Other machines can ask, within limits you set. An enrolled caller launches inside a profile's ceiling — the directories it may use, the strongest containment it may request. Configuration is the grant; the request never widens it.
• Every claim here was measured. Runtime behaviour is established by driving the real programs and recording what they did — see Verification. Where a finding later proved wrong, the correction is in the release notes rather than quietly edited away.

Claude requires a directory already trusted by the operator, or --options auto-approve-path. The automated suite uses fake runtimes, not real models; behaviour against real ones is verified by hand and recorded in RELEASE_NOTES.md.

Quick start

# Allow the install scripts: muster's postinstall builds node-pty, and npm
# skips install scripts by default — silently, so the pty host fails later.
npm install -g --allow-scripts=@brutalsystems/muster,node-pty @brutalsystems/muster

# A session: an agent you can reach, addressed once it is genuinely alive.
muster run claude --prompt 'Review this project' --cwd .

# A task: runs once, captures output, advertises nothing.
muster run codex --kind task --prompt 'Summarise the failing tests' --read-only
muster output <id>

# Knowing it has finished: block on it, or have muster run a command then.
muster wait <id> --timeout 30m
muster run codex --kind task --prompt 'Review' --on-exit 'notify "$MUSTER_STATE"'

# What is running, and stopping it.
muster list --format human
muster stop <id>

# Show a session in a terminal: terminal, iterm2, ghostty, or one you define
# under [open.apps] in config.toml (see docs/launching.md).
muster run claude --prompt 'Review this project' --open kitty

A Claude launch with no containment flag opens exactly as you would open it by hand in that profile and folder. It gets your rules and CLAUDE.md, your permissions, hooks, status line, plugins, MCP servers and settings env. Muster adds nothing and replaces nothing. The one thing it refuses is a profile whose default permission mode is bypass. Codex and OpenCode stay read-only by default.

When you want muster's guarantee instead, seal the launch. A sealed launch runs on muster's own settings in place of the profile's, so it loads no rules or CLAUDE.md:

Flag	The agent asks before acting	What it may touch
--read-only	always	nothing on disk
--write-here	no	its cwd, except ~/.muster
--unrestricted	no	everything

--unrestricted removes the sandbox and needs allow_dangerous_flags in config. --level read|work|open is the older spelling of the same three and still works.

Claude asks to trust a directory the first time. That is a one-time review you do yourself — or --options auto-approve-path, which records it for you after checking the directory ships no hooks. See Claude workspace trust.

Requirements

Node 22.12+ (tested on 24.16), and a POSIX host with ps and lsof. Terminals use tmux or node-pty. The OS sandbox is seatbelt, so kernel-enforced containment is macOS only; everywhere else enforcement reports what was actually applied rather than pretending.

Then whichever agents you mean to launch, installed and logged in. Verified against Claude Code 2.1.274, Codex 0.155.1 and OpenCode 1.18.31 or newer — a newer OpenCode must keep the CLI and loopback HTTP API Muster uses. What that verification covers is in Verification.

Documentation…