Skip to main content
Glama

Muster

license

Muster launches instructed Codex or Claude Code agents on this machine. A session returns an address only after its runtime is reachable. A task runs once, captures output, and never advertises a peer address.

Live launch verification: Codex and Claude both launched and answered their initial prompts without terminal interaction. Claude requires a directory already trusted by the operator. The automated suite uses fake runtimes, not real models.

Build and run locally

Requires Node 22.12+ (tested with 24.16), TypeScript 5, and Codex 0.155.1 / Claude Code 2.1.267. Terminal drivers use tmux or node-pty. Process discovery currently requires a POSIX host with ps and lsof; the terminal interface itself is platform-neutral. The macOS Terminal driver is an unavailable v1 stub.

Before launching a Claude session, open Claude normally in the target directory and complete its workspace-trust review yourself, then exit that setup session. This is a one-time prerequisite for each directory Claude requires you to trust. Muster never accepts trust prompts or changes trust settings. An untrusted directory can block startup; Muster times out and cleans up that launch.

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 codex --kind task --prompt 'Explain the test layout'
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.

For readable terminal output, add --format human to run, list, or stop:

muster run codex --prompt 'Review this project' --format human
muster list --format human
muster stop THREAD_OR_SESSION_OR_RUN_ID --format human

Human output keeps full IDs and shows directory, host, state, and relevant attach/output/stop commands with actual IDs. pty sessions are labeled as not watchable or attachable. --format json is explicit JSON; omitting the flag still returns JSON. Put Muster options before any -- RUNTIME_OPTIONS. output always prints captured task text and does not accept --format. MCP tools retain their existing JSON responses.

Human output uses subtle colors in interactive terminals: green for idle or running, yellow for busy or starting, gray for ended states and field labels, red for failures or nonzero exit codes, and cyan for follow-up commands. IDs and paths retain the normal text color. Set NO_COLOR=1 to disable colors; piped output and TERM=dumb are always uncolored. JSON never includes colors.

run accepts an optional -- followed by runtime arguments. The normal allowlist is --model / -m, plus Claude's --effort. Unknown options, bundled short options, config injection and raw permission overrides are refused, even with allow_dangerous_flags enabled. Use Muster's normalized permission flags. Prompt strings are passed as a single literal argument after the runtime's option terminator.

Related MCP server: pokeclaw

Terminal lifetime

Auto-selection tries tmux, then pty. Every peer includes host, capabilities and attach_hint. Watchability is separate from the runtime's idle/busy state.

  • tmux: a window in the dedicated muster session on the muster tmux server. Watchable and attachable; survives the CLI or MCP server exiting. Use the returned attach hint, or tmux -L muster attach -t muster.

  • pty: not watchable or attachable. The CLI prints the peer record and stays running to own the terminal. Ctrl-C stops it. MCP-owned pty sessions stop when the MCP server disconnects. There is no persistent pty daemon.

  • task: a per-run worker captures stdout/stderr and exit status after the launching CLI exits. It supervises one task, with no retry or restart behavior.

list refreshes live session metadata and shows ended runs distinctly. A timeout or startup failure cleans the process tree and host window, logs failure, and returns an error instead of a peer record.

Configuration and permissions

Muster reads ~/.muster/config.toml once at startup and never writes it. Missing configuration uses these defaults:

host = "auto"
launch_timeout_sec = 30
max_concurrent = 4
permissions = "deny"
sandbox = "read-only"
allow_dangerous_flags = false

Choose sandbox = "workspace-write" yourself when agents should edit files. full-access and permissions = "bypass" require allow_dangerous_flags = true. The old config spelling danger-full-access remains accepted as an alias.

Per-launch --permissions and --sandbox override these config defaults. The same named fields are accepted by MCP run. Both session and task launches support them:

muster run codex --permissions auto --sandbox workspace-write \
  --prompt 'Implement the change' --format human
muster run claude --permissions auto --sandbox workspace-write \
  --prompt 'Implement the change' --format human

Muster permissions

Codex translation

Claude Code translation

deny (default)

Approval policy never

Permission mode dontAsk

auto

--approve-for-me

Permission mode auto

bypass

Bypass approvals and sandbox

Permission mode bypassPermissions

deny refuses actions that would require approval; it does not prohibit tools already allowed by the sandbox or permission rules. auto delegates permission review to the runtime and may still reject an action; it is not blanket approval. Auto mode requires workspace-write in Muster because the Codex preset selects that sandbox. Explicitly select it; Muster never widens a read-only request. Bypass requires full-access; combinations claiming a sandbox while bypassing it are refused. deny can be combined with any authorized sandbox setting.

full-access disables the runtime command sandbox and requires operator-owned config authorization even without bypass. Muster never writes that config. Config defaults apply to subsequent launches; overrides apply to one launch. Resolved permissions and sandbox are returned in records, shown in human output, persisted for listing, and written in the pre-launch log. Old records without those fields remain readable; their settings are not guessed.

The runtimes' enforcement differs: Codex reviews sandbox escalation requests; Claude's classifier reviews tool permission requests while its Bash sandbox is separate. Auto-mode availability and decisions remain subject to runtime, model, account, and managed policy. These fields describe Muster's resolved launch settings, not a continuous attestation of remote policy or user changes. See Codex auto-review and Claude permission modes.

The concurrency cap is shared by separate CLI/MCP processes, including pending launches. Settings apply to both kinds; tasks are read-only by default.

Codex defaults to an explicit sandbox and never-ask approval policy. Muster enumerates and explicitly disables inherited MCP servers, then verifies the effective configuration. Hooks, plugins, app connectors, automatic skill-MCP installation and external notifications are disabled for the child. Unknown MCP names that cannot be addressed safely are refused.

Claude's built-in tools default to enabled. Unless full access is selected, its command sandbox is enabled, requires availability, and forbids unsandboxed retries. File-writing tools and sandbox writes are denied in read-only mode; default permissions use dontAsk so an unattended child does not auto-grant escalations. User/project settings and MCP servers are not inherited. Detected managed policy is refused because the CLI cannot prove that inline settings override it. Enterprise remote policy can arrive after startup; this v1 is not an enterprise policy-enforcement layer. Claude permissions and its command sandbox are different mechanisms; neither claim implies that every external tool is OS-sandboxed.

These child restrictions deliberately prevent propagating spawn authority. Custom MCP tools—including Tin Can—are not automatically injected into the child. The child's runtime inbox remains reachable from an external Tin Can. No user-level runtime configuration is rewritten, and workspace-trust dialogs are never accepted automatically.

Launch intent is fsynced to ~/.muster/launches.jsonl before a runtime starts; ready/failure outcomes follow. The log contains the full prompt, cwd, requester, runtime, kind and host. Registry and task outputs also live under ~/.muster, with private file permissions. An abandoned registry.lock fails closed: verify no Muster operation is running before removing that directory. There is no automatic time-based lock theft.

MCP installation

Installed deliberately, in the one session that should hold spawn authority — never at user scope.

Muster exposes run, list, stop, and output over stdio. No arguments or mcp starts the server. Diagnostics go to stderr, never protocol stdout. Schemas match the CLI (args is the array of optional runtime arguments).

For a single Codex session, use per-invocation configuration:

codex -c 'mcp_servers.muster.command="node"' \
  -c 'mcp_servers.muster.args=["/absolute/path/to/muster/dist/muster.js","mcp"]'

For a single Claude session:

claude --mcp-config '{"mcpServers":{"muster":{"command":"node","args":["/absolute/path/to/muster/dist/muster.js","mcp"]}}}'

Do not add Muster to ~/.codex/config.toml, Claude's user-scope MCP registry, or another shared configuration that grants launch authority to every agent.

Tin Can compatibility

Muster has no Tin Can build or runtime dependency. Each tool implements the written address contract independently. Vendored mechanics carry source-commit headers and the original MIT license in TINCAN_LICENSE.

Addresses belong to running sessions and can expire or collide. Store thread_id / session_id, and re-resolve through Tin Can's peers before sending instead of caching a launch address. Canonical IDs are not unique keys. The frozen cases intentionally preserve Tin Can's known naming defects.

Codex idle means reachable and not known to be busy, not guaranteed free. The querying app-server can report notLoaded for a live thread; Muster maps that to idle. Claude state comes from its session registry.

Verification

npm test
npm run build
npm run test:contract

The ordinary suite requires tmux, node-pty, POSIX ps/lsof, and Python 3 for real file locks in the fake Codex executable. It uses isolated runtime homes and no model APIs. It skips the four explicitly invoked compatibility cases.

The verified contract baseline is Tin Can 0.2.0. The suite spawns an installed binary as an MCP subprocess, compares durable IDs, and verifies delivery to fake runtimes through both terminal hosts. A missing binary or missing durable field fails the test. For reproducible verification, install that exact release outside Muster:

contract_dir=$(mktemp -d)
npm install --prefix "$contract_dir" --no-save @brutalsystems/tincan@0.2.0
MUSTER_TINCAN_BIN="$contract_dir/node_modules/.bin/tincan" npm run test:contract

Verification uses the published 0.2.0 release installed in an isolated temporary directory. No Tin Can source edits are made. Fixture version metadata alone does not indicate address-format drift: compare the case arrays. Those arrays cover naming only, not peer-list membership or state semantics. Upgrades require separate compatibility verification; passing fixture hashes alone does not establish compatibility. The tests locate the launched peer by canonical ID and compare its durable ID; they do not assert a total peer count, exclude same-runtime peers, or assert Tin Can's busy state. CONTRACT_PROVENANCE.md records both types of integrity checks.

One-time live probes are separate from the automated suite. Both runtimes launched and answered an initial prompt with the versions listed above; Claude used a directory already trusted by its operator. npm test does not run real models.

License and releases

MIT © 2026 Mike Williams. See LICENSE. Vendored Tin Can code retains source attribution and its MIT notice.

RELEASING.md covers versioning, package inspection, publication, and release notes. Changes to the shared address format require an explicit contract update; Muster never independently fixes the frozen naming behavior.

Available Tools

4 tools
listA

List Muster-owned sessions and tasks, including host capabilities.

ParametersJSON Schema
NameRequiredDescriptionDefault
kindNo

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It describes the action as non-mutating ('List'), which implies a read-only operation, but it does not explicitly state there are no side effects, nor does it mention authentication requirements, pagination, or output format. 'Including host capabilities' hints at extra data, but no details are given. This is adequate for a simple list tool but not richly transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that front-loads the primary purpose ('List Muster-owned sessions and tasks') before adding the secondary detail about host capabilities. It contains no filler or repetition, and its brevity is appropriate for a tool with only one optional parameter.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (one optional enum parameter, no output schema, no annotations), the description covers the main purpose but leaves gaps: it does not explain the 'kind' parameter's effect, nor does it describe the return structure. The phrase 'including host capabilities' suggests extra output but is undefined. For a simple list tool, this is moderately complete but not fully self-sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description does not explain the 'kind' parameter at all. The schema provides an optional enum of 'session' or 'task', but with 0% schema description coverage, the description should clarify how this parameter filters results. The overview says 'sessions and tasks' but not that 'kind' selects between them. This is a meaningful gap, as the parameter's role is left entirely to inference from the schema's enum values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the operation: 'List Muster-owned sessions and tasks'. It uses a specific verb ('List') and names the resource, which distinguishes it from siblings like 'run', 'stop', and 'output'. The additional 'including host capabilities' makes the scope more specific without confusing the core purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: the agent should call this when it needs to enumerate existing sessions/tasks. However, it does not explicitly state when to use it over alternatives (e.g., before running or stopping), nor does it describe when not to use it. There is no mention of prerequisites or routing to siblings, leaving the agent to infer the use case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

outputC

Read captured output from a task run.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes

TDQS

C2.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It only says 'Read', implying a non-mutating operation, but does not state whether the task must be finished, whether it blocks, what happens if the id is invalid, or what the output format is. The description is too sparse to convey essential behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence, which is concise, but it is under-specified. It lacks essential context that should be present given the absence of annotations and parameter descriptions. The brevity works against the agent rather than aiding it, so it is not appropriately sized for the tool's needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one parameter, no annotations, and no output schema, the description is severely incomplete. It does not explain what the 'id' is, what 'captured output' means, how to obtain the output, or what the response will look like. An agent cannot reliably invoke this tool correctly based on the provided definition.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has a single required parameter 'id' with no description, and schema coverage is 0%. The description does not explain what 'id' refers to (presumably a task run ID) or how to obtain it. The agent has no information about the parameter's meaning, format, or constraints beyond a minLength of 1.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Read' and the resource 'captured output from a task run', which distinguishes it from sibling tools like run, list, and stop. However, it is slightly vague about what 'captured output' includes (e.g., stdout, stderr, logs), so it does not fully specify the resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives such as list or run. It does not mention prerequisites like the task needing to be completed, nor does it contrast with siblings. The agent is left to infer usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

runA

Launch an instructed agent. Sessions return only when reachable; tasks return a non-messageable run handle.

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNo
argsNo
hostNo
kindNosession
promptYes
runtimeYes
sandboxNoDefaults to config (read-only). Full access requires config authorization.
permissionsNoDefaults to config (deny). Auto requires workspace-write; bypass requires authorized full-access.

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the safety/behavior burden, and it does disclose a non-obvious trait: sessions return only when reachable, while tasks return a non-messageable run handle. However, it does not mention side effects, auth requirements beyond the schema's sandbox/permissions notes, or how the returned handle is consumed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler; the core action is front-loaded and the return-behavior nuance is compressed into the second sentence. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With eight parameters, five enums, no output schema, and no annotations, two sentences leave too many operational gaps (defaults, host/runtime choice, handle consumption). The session/task distinction helps, but an agent still lacks enough to call this complex tool confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 25%, and the description compensates only for `kind` by defining session vs task return behavior. cwd, args, host, runtime, and prompt remain semantically unexplained in either the schema or the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Launch') with a clear resource ('an instructed agent') and immediately defines a meaningful sub-distinction between sessions and tasks. This makes it easy to distinguish from the sibling management commands list, stop, and output.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for starting an agent and clarifies the session/task return contract, but it never states when run should be preferred over list/stop/output or gives exclusions/prerequisites. Usage context is inferable from the name and siblings, not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

stopA

Stop a Muster-owned run by durable id or unambiguous peer name.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only says 'Stop,' implying a mutating action, but does not disclose whether stopping is irreversible, what happens to the run's output, permission requirements, or idempotency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler. Every part contributes: the action, the resource scope, and the accepted identifier forms.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple and the description covers the action and parameter semantics, so an agent can likely invoke it correctly. However, with no annotations and no output schema, it omits behavioral consequences and does not mention how to obtain the id or name, despite the sibling list tool existing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one required string id with no description (0% coverage). The description adds crucial meaning by explaining that id can be a durable id or an unambiguous peer name, which is not derivable from the schema. It does not define the formats, but it compensates well for the schema gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses a specific verb ('Stop') and names the exact resource ('Muster-owned run'), plus the identifier forms accepted. It is clearly distinct from siblings run, list, and output.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for stopping an existing Muster-owned run and even states how to identify it, but it does not explicitly mention when not to use it or direct the agent to list for finding ids. Usage context is clear but alternatives are left implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.3.0
    • First observedlist
    • First observedoutput
    • First observedrun
    • First observedstop

TDQS

B3.4/5.0

Scored across 4 tools

Disambiguation5/5

Each tool targets a distinct concern: launching a run, listing resources, stopping a run, and reading output. There is no meaningful overlap between actions.

Naming Consistency4/5

All tools use short, lowercase, single-word names in an imperative style, which is consistent overall. 'output' is slightly noun-like compared to 'run', 'list', and 'stop', but it still reads as a clear command.

Tool Count5/5

Four tools is a tight, well-scoped set for a small agent/session management server. Each tool has a clear role with minimal redundancy.

Completeness4/5

The core lifecycle of launch/list/stop/read-output is covered. Minor gaps exist around explicit status checking, session-level output, or cleanup/removal, but agents can likely work around these with list and stop.

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    D
    maintenance
    Wraps Claude Code as tools for MCP clients, enabling autonomous coding tasks via a 4-tool lifecycle with session management, async polling, and permission controls.
    4
    34 npm
    20
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables MCP clients to spawn and control Codex CLI and Claude Code sessions on the host machine, with session management and filesystem access.
    4
    MIT
  • F
    license
    Not graded
    quality
    C
    maintenance
    Enables ISLI agents and MCP clients to dispatch natural-language coding and terminal tasks to a locally-installed Claude Code CLI, supporting both one-shot execution and persistent sessions with workspace and security controls.
    -
  • F
    license
    Not graded
    quality
    A
    maintenance
    Agent orchestration system that runs coding-agent sessions (Claude Code, Codex) with policy mediation and exposes tools via MCP.
    -