Launches Claude Code, Codex and OpenCode coding agent sessions on your machine with configurable containment and returns a reachable address.
Also known as BrutalSystems/muster, @brutalsystems/muster
- Stars
- 1
- Tools
- 2
- Downloads, 30 days
- 6,630
- Latest version
- —
- Last commit
- Nov 3, 2026
- License
- MIT
What is Muster MCP?
Muster launches Claude Code, Codex and OpenCode coding agent sessions on your machine with configurable containment and returns a reachable address. It exposes 2 tools, such as list, output.
Summary generated from the project's README
About Muster MCP server
Muster starts Claude Code, Codex and OpenCode coding-agent sessions on your own machine, applies the containment you specify, checks that the runtime is actually listening, and only then returns an address you can reach. It suits developers who run several agents on purpose: one reviewing while another builds, a one-shot job whose output is captured, or an agent launched under a separate account so it never touches your own configuration. A session is reported ready only after Muster confirms the runtime is live; a task runs once, captures its output and advertises no peer address.
It runs locally as a global npm package requiring Node 22.12+, a POSIX host with ps and lsof, and tmux or node-pty for terminals. Kernel-enforced sandboxing is seatbelt, so OS-level containment is macOS only, and elsewhere the enforcement field reports what was applied. Containment splits into two questions: whether the agent pauses to ask, and what it may touch, chosen with flags such as --read-only, --write-here and --unrestricted; the last drops the sandbox and needs allow_dangerous_flags in config. Commands include run, list, output, wait, stop and mcp install. Claude launches untampered use your profile unless sealed; Codex and OpenCode stay read-only by default.
Muster refuses unrecognised or contradictory flags before starting anything, and remote callers it has enrolled can launch only inside a profile's ceiling. Its MCP server is offered either through the Claude Code plugin that teaches the skill and starts a read-only server via npx, or through muster mcp install, where --allow-launch adds run, stop, title and open. Use one, not both.
What you can do with it
- 1Launch a reviewing Claude sessionHave the client start a Claude Code session that reviews a project in a given directory and hand back an address once the agent is reachable.
- 2Run a one-shot codex taskAsk the client to run Codex read-only against a prompt, capture its summary of failing tests, and fetch the output later.
- 3Block until an agent finishesLet the client wait on a running job for up to thirty minutes instead of polling, or trigger a command when it exits.
- 4List and stop running agentsHave the client show what sessions are currently running and stop a specific one by its identifier.
- 5Grant launch rights to a sessionEnable the MCP server with launch authority so a Claude session can start and stop sessions in that profile.
Written from the project's README. Every use case is checked against a quote from it.
How to install Muster MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Muster MCP in Claude Code
$ claude mcp add muster -- npx -y @brutalsystems/musterInstall Muster MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"muster": {
"command": "npx",
"args": [
"-y",
"@brutalsystems/muster"
]
}
}
}Install Muster MCP in VS Code
.vscode/mcp.json
{
"servers": {
"muster": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@brutalsystems/muster"
]
}
}
}Install Muster MCP in VS Code CLI
$ code --add-mcp '{"name":"muster","type":"stdio","command":"npx","args":["-y","@brutalsystems/muster"]}'Install Muster MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"muster": {
"command": "npx",
"args": [
"-y",
"@brutalsystems/muster"
]
}
}
}Install Muster MCP in Codex
$ codex mcp add muster -- npx -y @brutalsystems/musterInstall Muster MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.muster] command = "npx" args = ["-y", "@brutalsystems/muster"]
Install Muster MCP in Gemini CLI
$ gemini mcp add -s user muster npx -- -y @brutalsystems/musterInstall Muster MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"muster": {
"command": "npx",
"args": [
"-y",
"@brutalsystems/muster"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @brutalsystems/muster 3.16.1 in an isolated container with no network and no keys. It answered and listed 2 tools.
Muster MCP tools 2
Read from the server with tools/listlistRead-onlyList Muster-owned sessions and tasks, including host capabilities.
outputRead-onlyRead captured output from a task run.
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubMuster
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
| How a launch runs | hosts, terminals, lifetimes, repeated requests |
| Configuration and permissions | containment, config file, remote callers |
| Agent identities | running as a named account |
| Claude workspace trust | the one-time dialog, and the two gates behind it |
| Command-line reference | output formats, runtime pass-through |
| MCP servers and plugins | tools for launched agents, and Muster's own MCP server |
| Verification | what is tested, what is checked by hand |
Use with Claude Code
-
Install the plugin. Its
musterskill teaches a Claude session to use Muster well: choosing a kind and level, reaching and stopping what it launched, and the traps. It also brings Muster's MCP server, read-only (list,output), started withnpxat the release the plugin came from. Both are versioned with Muster, so they describe and run the same release.claude plugin marketplace add BrutalSystems/muster claude plugin install muster@musterOr, inside a session,
/plugin marketplace add BrutalSystems/musterand then/plugin install muster@muster.The plugin's server needs Node 22.12+ with
npxon PATH. On macOS and Windows, node-pty loads a prebuilt binary. On Linux,npxbuilds node-pty from source the first time, which needs Python,makeand a C++ compiler; without them, use the global install and step 2 instead. -
Or register the MCP server yourself, when you want launch authority or a server that runs your global
muster:muster mcp installIt is read-only by default too.
muster mcp install --allow-launchaddsrun,stop,titleandopen, and every session in that profile can then launch and stop sessions.muster mcp statusshows which you have. Use the plugin's server or this one, not both: see plugin or registration. Details: MCP installation. -
Restart Claude Code (or start a new session) to load it.
Keeping it up to date
Publishing a release does not touch an installed copy: muster --version keeps
reporting the old version until you update it.
npm update -g @brutalsystems/muster
If which muster resolves to a version-manager shim (for example
~/.asdf/shims/muster), run that update under the Node the shim resolves to and
reshim afterwards — asdf reshim nodejs — or the shim keeps pointing at the old
binary.
The plugin, and the server it pins, update with the marketplace:
claude plugin marketplace update muster
claude plugin update muster@muster
An MCP server starts once at session startup, so an agent session that already has Muster loaded keeps running the old binary until that session restarts. Updating on disk is not enough; restart the session too.
Build and run locally
npm run check is the local gate: it builds, runs the suite, then packs and
verifies the tarball — the same scripts/check-tarball.mjs the CI packing job
runs, so the two cannot disagree about what "verified" means. npm test alone
does not pack anything, so tarball drift is green locally and red on push.
It is not everything CI does: CI additionally runs the suite across the Node
version matrix, and the contract suite runs only on release. Passing check is
necessary rather than sufficient.
Beyond the runtime requirements above, building needs TypeScript 5. The terminal interface itself is platform-neutral; the macOS Terminal driver is an unavailable v1 stub.
npm ci
npm run build
node dist/muster.js run codex --prompt 'Review the authentication flow'
node dist/muster.js run claude --prompt 'Summarize the project' --host tmux
node dist/muster.js run opencode --prompt 'Review this project'
node dist/muster.js run opencode --prompt 'Build a plan' -- --model local-provider/qwen3-30b
node dist/muster.js run codex --kind task --prompt 'Explain the test layout'
node dist/muster.js run opencode --kind task --prompt 'Summarize the tests'
node dist/muster.js list
node dist/muster.js list --format human
node dist/muster.js list --kind task
node dist/muster.js output RUN_ID
node dist/muster.js stop THREAD_OR_SESSION_OR_RUN_ID
--prompt is required and cannot be blank. --cwd defaults to the current
working directory. --kind defaults to session. All commands except output
emit JSON; output prints the captured task output. stop also accepts an
unambiguous peer name or canonical address, refusing ambiguity with candidates.
Use the durable ID to stop a session whose runtime has renamed it.
License and releases
MIT © 2026 BrutalSystems. See LICENSE. Vendored Tin Can code retains source attribution and its MIT notice.
Publishing is tag-driven and runs in GitHub Actions over OIDC trusted
publishing, with no stored npm token. A bare git push publishes nothing; a
version tag is what triggers publish.yml. That workflow validates a RELEASE_NOTES.md section for
the version being published, so write the notes under ## Unreleased as you do
the work and commit them normally. Cutting the release is then one command:
git commit -am "<the change, including its notes under ## Unreleased>"
npm version patch -m "%s — <what changed>"
npm version runs the version hook, which stamps ## Unreleased into
## <version> — <date> and stages it, then bumps, commits and tags; the
postversion hook pushes the commit and tag together. If there is no
## Unreleased section, or it is empty, the stamp refuses — before a tag
exists, rather than in CI after one has been pushed.
RELEASING.md covers versioning, package inspection, publication, and release notes in full. Changes to the shared address format require an explicit contract update; Muster never independently fixes the frozen naming behavior.
Muster MCP questions
How do I add Muster MCP to Claude Code?
Run claude mcp add muster -- npx -y @brutalsystems/muster in your terminal. Add --scope user to make it available in every project.
How do I add Muster MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Muster MCP provide?
It exposes 2 tools, including list, output.
Which coding agents can Muster launch?
Muster starts Claude Code, Codex and OpenCode sessions on your behalf. It is verified against Claude Code 2.1.274, Codex 0.155.1 and OpenCode 1.18.31 or newer.
What containment levels can I give a launched agent?
There are three sealed levels: --read-only (agent asks and touches nothing on disk), --write-here (no asking, limited to its cwd) and --unrestricted (everything, requires allow_dangerous_flags).
Does the MCP server let an agent launch sessions?
By default the MCP server is read-only with list and output. Running muster mcp install --allow-launch adds run, stop, title and open tools.
What happens if a session never becomes reachable?
Muster only reports a session ready once its runtime is genuinely reachable, and otherwise returns a diagnosis naming what stopped it instead of a process that looks fine but isn't.
Does the OS sandbox work on Linux?
Kernel-enforced containment uses seatbelt, so it is macOS only; elsewhere enforcement reports what was actually applied.