Inside Muse Code: Subagent Fan-Out, Skills, Event Logs

Muse Code, Meta’s terminal and CI coding agent, went into beta on August 5, 2026 alongside Muse Spark 1.2 — and the part worth your attention is not the model. It is the harness. One job fans out to parallel subagents that each get their own git worktree, and every model call, tool run, approval and edit lands in an append-only event log that a killed session can resume from instead of starting over.

That combination is unusual. Plenty of coding CLIs can spawn subagents; plenty can write a transcript. Very few treat durability as a first-class product surface, with a documented intent-before-effect ordering, a byte-deterministic export format, and a resume path that inspects real state before it re-runs anything. If you are evaluating agent harnesses for real repository work rather than demos, that is the axis that decides whether a long-running job is trustworthy.

This guide is the hands-on tour: install and first run, the approval and sandbox model, how fan-out and worktree isolation actually behave, what the event log records, the four bundled skills the product docs list (which is not the set the launch announcement described), the boundary between Muse Code itself and Meta’s Model API cookbook demos, and an honest read of what is still rough. Every harness mechanic below comes from Meta’s own product documentation and cookbooks, checked at the time of writing; the pricing, evaluation and practitioner-reaction material is sourced separately where it appears.

Installation is a single line on macOS and Linux: curl -fsSL https://dev.meta.ai/install.sh | bash. Run muse inside a project directory and the first-run flow asks two things: whether to trust this workspace — trusting it loads the project’s skills, rules and hooks — and how you want to authenticate, via browser sign-in or an API key. The default model is muse-spark-1.2. For the model side of the launch and what shipped with it, see our Muse Spark 1.2 and Muse Code launch guide; this piece stays on the harness.

Two authentication details matter in practice. Meta Managed Account users cannot use browser sign-in at all — it is API-key authentication only, through the META_API_KEY environment variable or the /login command. And the precedence order is worth memorising before you debug a “wrong account” problem: the environment variable beats a stored key, which beats a stored browser session. muse logout clears stored credentials but leaves an exported environment variable exactly where it was.

Muse Code ships closed rather than open. Approval prompts and an OS-level sandbox are both active out of the box, and the sandbox is native rather than emulated: Seatbelt on macOS, a bundled bubblewrap helper on Linux. It grants write access to the workspace plus a temp directory and keeps the rest of the filesystem read-only. Inside that writable workspace there are three exceptions — .git, .muse and .agents stay read-only even to the agent, so it cannot rewrite its own history, its own configuration, or its own memory.

One behaviour here is genuinely strict, and it is the right default: if Muse Code cannot confirm the sandbox is active, it refuses to run shell commands at all. A Linux host without a working bubblewrap, or a musl build shipped without the helper, fails every shell command as an environment error instead of quietly running unsandboxed. That is the opposite of the failure mode we keep seeing in agent tooling — for the wider pattern of where agent isolation leaks, our write-up on coding-agent sandbox escapes and command filters covers what these boundaries typically fail to hold.

The detail that separates this from a simple allow-list is that compound shell commands are reviewed stage by stage, not as one line. Meta’s own worked example is wc -l report.log && echo cleaning && rm -rf report.log, which parses into three stages: the two read-only stages clear automatically, and the rm -rf stage holds for review. The whole command then runs as one unit only after every stage clears. Reject a single stage and nothing runs — not even the safe stages that came before it.

When a stage holds, you get three trust scopes. “Allow once” persists nothing. “Always allow in this workspace” saves an argv-prefix rule scoped to that workspace root into an approval policy file. “Reject” denies the entire command. Interpreter prefixes can never be saved as a broad allow — python, bash, sh, node, perl, ruby, php, env, sudo and bare git are all excluded, because everything after an interpreter is arbitrary code. A deny always overrides an allow, regardless of which rule is more specific.

Network access has its own three settings. The default, proxy-only, treats the first connection to a new host, port or protocol like a shell command and stops for review; restricted means no network; enabled means full egress. Note that --disable-sandbox forces full network egress regardless of what the network mode says.

Fan-out in Muse Code means a parent agent spawning write-capable child agents. What makes it more than a thread pool is the isolation: with --subagent-worktree-isolation, the runtime creates and owns a git worktree per child under a repo-relative .muse/worktrees/ directory, in detached HEAD state, checked out from the parent’s HEAD. You never type a git worktree command, and the children cannot collide on the same files, because they are not editing the same files.

Control is exposed both to the model and to you. The native tools are subagent_spawn (role, objective, worktree isolation), subagent_status, subagent_send_message, subagent_cancel, subagent_wait and subagent_read_result. In the TUI, /agent or /subagents opens the view, with /agent-note, /agent-followup, /agent-interrupt, /agent-stop, /agent-resume, /agent-reopen and /agent-close for steering. Parallel-agent CLIs are a crowded field now — xAI’s Grok Build and its parallel coding agents arrived at a similar shape from a different direction.

Concurrency is not unlimited. Both of Meta’s pages describe the same formula — roughly host core count minus two — and then disagree on the clamp applied to it, so the chart below shows the formula alone, before any clamp. Treat the resulting number as the unclamped formula result — your host’s real cap may land above or below it — and check what your own machine actually does.

Three behaviours will bite you before anything else does. First, subagents are one level deep — a child cannot spawn its own children, so a plan that assumes recursive delegation will quietly flatten. Second, cancellation is cooperative: a cancelled child that never reaches a checkpoint keeps running, and one that is mid-write finishes that write. Third, a queued steer only applies on the child’s next turn. In Meta’s own recorded demonstration, a child told to rename its output file finished the turn and produced the old filename anyway before the message landed. For a hard redirect, send the message with the interrupt option so it preempts the child’s current turn instead of waiting politely behind it.

Muse Code writes one append-only log per session to a date-stamped path. Each line is an envelope with a sequence number, a recorded timestamp, a record type, a durability marker, a payload type and the payload itself. Subagents and observers do not share the parent’s file — each writes its own log beneath the session directory, under a per-child path, so a fan-out produces a tree of logs rather than one interleaved stream.

The invariant that matters is intent before effect: nothing externally visible happens without a durable record written first. A side effect is logged as a proposal, then an acceptance, then an approval review request, then the applied decision, then a side-effect intent carrying the policy decision that authorised it, then the started effect, and finally a terminal record — seven records in Meta’s documented ordering, in that order. A crash between the intent record and the terminal record is precisely what makes the run recoverable, because the log tells you the effect may have happened without telling you it definitely did.

That is a different guarantee from a checkpoint, and it is worth being precise about which one you are relying on — our reference on agent rollback and checkpoint patterns splits the tiers: filesystem undo, database undo, and external side effects that no snapshot can retract. An event log with idempotency keys is aimed squarely at the third tier, the one checkpoints cannot reach.

The redaction mode is useful but not absolute. muse export --redacted strips authentication headers, secret-keyed assignments, PEM blocks, bearer and provider tokens and JWTs using the same telemetry redaction rules the runtime applies elsewhere. Encrypted reasoning blobs, though, stay verbatim in both raw and redacted output. If you are handing an export to someone outside the team, that is the field to think about before you send it.

Resuming has one ergonomic trap. muse resume expects an interactive terminal; run it from a script or pipe it and it exits instead of resuming. For scripted continuation, use muse resume --last for the most recent session in the workspace, or muse resume with an explicit session UUID. For a fully headless continuation, muse exec --session-id with the session UUID and a short instruction picks the thread back up without a TUI at all. Each intent also carries an idempotency key, written before its effect runs, so you can check the log for duplicate firing rather than guessing.

The coverage we checked repeats the announcement’s description of three skills: /plan, /grill and /goal. Meta’s own product documentation describes something different — four built-in, on-by-default skills, none of them named /grill, and goal tracking implemented as a separate command rather than a skill. The product docs are the more detailed, product-level surface, so that is what we have followed throughout this guide. Here is the reconciliation.

Skills load lazily, which is the design decision that keeps a large catalogue affordable. At session open only skill summaries enter the context. Invoking a slash shortcut pulls that skill’s full definition file through a read-skill tool call, scoped to that one turn — the TUI prints a line naming the loaded skill and marking it built-in at the moment it happens, so you can see the cost land. Skills are also explicit-invocation only: Muse Code does not fire /plan because a task looks complex, and does not fire /grilling because a request is underspecified. That boundary is written into each skill’s own description rather than left to the model’s judgement.

Custom skills load from three places: built-in, user-level (under the XDG config directory for muse, and ~/.agents/skills), and project-level at .agents/skills/ inside the repository, which is the one you commit and share with the team. Muse Code also scans repo-local .codex/skills and .claude/skills directories, and ships muse skills import --from claude and --from codex. That is a deliberate migration ramp: your existing skill library is treated as portable input rather than a reason to stay put.

Goals and the four background observers

The /goal command pins an objective and an acceptance check for the session. Roughly every ten model calls with no reported progress, a step probe queues a note telling the agent to continue working toward the active goal, shown in the TUI as a goal reminder row. Closing the goal is gated by a completion audit, so the agent has to verify against the objective — running the actual test suite, for instance — before it can mark the goal done. Meta’s own failure-mode note is the practical instruction: name the exact oracle in the objective, such as requiring all six checks in a named test file to pass, or the agent can declare victory against a vague finish line.

Separately from write-capable spawned subagents, Muse Code runs four background observer agents alongside the main session: memory recall, skill recall, goal tracking and verification. Each proposes an advisory to the main agent’s next turn, and a reconciler decides whether that advisory actually reaches the model. Memory, skill and goal recall are on by default; verification is off. The budget consequence is easy to miss — every observer that runs makes its own model calls, so token usage for a session is the main thread plus whatever the observers spent, not the main thread alone.

This is the distinction most launch coverage flattens, and it changes what you can actually adopt. Two of the headline cookbooks — the autonomous GitHub bot and computer use — do not run on the muse binary at all. They run on OpenCode, a separate open-source terminal coding CLI, driving Muse Spark 1.1 through the Meta Model API. They are model demonstrations, and good ones, but installing Muse Code does not give you either of them.

The GitHub recipe is worth reading on its own merits even though it is not a Muse Code feature. It builds an issue-triage and PR-review bot that runs entirely on your own GitHub Actions runner, with a quality gate that screens for low-effort AI output, cited answers to repository questions, and bug-fix pull requests that only open behind a maintainer’s explicit comment or label. Web fetching is off, and shell access is a default-deny allowlist. Compare that posture with the platform-level approach in GitHub’s own multi-agent platform play — one is a repository you own and can read end to end, the other is a managed surface.

The computer-use recipe drives a disposable Linux desktop container through a small MCP bridge exposing screenshot, click, type and shell tools, in a look-act-look loop. The demonstrated task is finding and playing Minesweeper: the model located GNOME Mines, launched it and cleared an 8×8 board, delegating to short-lived sub-agents to stay under the Model API’s fifty-images-per-request limit. A sibling recipe does the same against a real macOS desktop with native input events instead of a container. Both are useful proof that the model can operate a screen; neither is something the muse binary does.

Two more native surfaces are worth flagging because they sit outside the containment story. Hooks bind shell commands to lifecycle events across session start, prompt submission, tool use, permission requests, model calls, context compaction, subagent start and stop, and session stop. Project and user hooks require an explicit trust command before they run, and managed hooks pointed at by a central setting are pre-approved for administered fleets. But a hook’s command runs outside the sandbox and approval system that governs the agent’s own tools — Meta’s docs say only add hooks whose commands you have read. MCP servers carry the same asymmetry: approval still applies to MCP tool calls, but filesystem and network containment does not, because the server is an ordinary child process or a direct network connection. A server marked required that fails to start aborts the whole run unless you mark it optional.

The launch thread on Hacker News drew 201 points and 117 comments at the time of writing, and the split in it is instructive: the harness mechanics get genuine credit while the model’s portability and the cheap tier’s terms take the criticism. One commenter singled out exactly the two features this guide spends the most time on — workers in separate worktrees, and crash recovery. Another described Muse Code as rough around the edges but, combined with the near-free contributor model, good enough to sit alongside a rival parallel coding CLI.

The sharpest criticism is about harness lock-in. A commenter reported trying Muse Spark through OpenCode and an aggregator rather than Meta’s own harness, and found it could not complete a simple task, getting stuck cycling through grep and search tools — their read was that the model has been reinforcement-trained so heavily against Meta’s harness that it becomes token-inefficient or unusable elsewhere. A second commenter agreed, expecting other harnesses to fail similarly. If that generalises, benchmark numbers from the vendor’s own harness say less about the model than they appear to.

There is also a verification gap you should know about before quoting anyone’s numbers, including ours. Per press coverage of Meta’s methodology page, the 1.2 evaluations cover all 89 Terminal-Bench 2.1 tasks at pass@1 over five attempts, 113 DeepSWE tasks spanning 91 repositories and five languages, and an internal coding benchmark of 440 tasks derived from real internal pull requests, all run in isolated cloud sandboxes against a comparison set that includes several rival frontier models. The scores themselves, though, are published as chart images with no machine-readable figures, and that same coverage reports Meta noting its own harness may not be tuned for third-party models. We have deliberately printed no 1.2 benchmark score in this guide, because we could not read one from a primary source rather than an estimate off a picture.

Finally, the install path is documented for macOS and Linux. One of the more pointed comments in the thread turned that into a benchmark of its own — the jab being that a coding agent good enough to trust ought to have been able to produce its own Windows build. It is a joke with a real edge for teams whose developers are not all on Unix.

The strategic read of this release is that the durability layer, not the model, is the product claim. Coding agents have spent two years competing on capability benchmarks that are increasingly hard to compare across harnesses. Muse Code competes on a different axis entirely — whether a multi-hour, thousand-tool-call run can be audited, exported with a hash that pins it, and resumed after a crash without repeating side effects. Meta’s own kernel-optimisation case study leans on exactly that: an agent iterating over more than a thousand tool calls across up to twenty-four hours, writing, compiling, profiling and improving GPU kernels it was required to implement itself rather than import. A run of that length is a durability problem long before it is an intelligence problem.

Our expectation is that this axis becomes table stakes rather than a differentiator within a couple of release cycles. Event-sourced agent runtimes are not a hard idea; they are a discipline, and the first vendor to ship one as a documented, exportable, deterministic format sets the shape everyone else copies. What is harder to copy is the surrounding posture — refusing to run shell commands when the sandbox cannot be confirmed, keeping the agent out of its own git directory, staging compound commands. Those choices reflect a view about what agents will do wrong, and that view tends to be sticky.

A sane rollout looks like this. Start interactive on a scratch branch to learn the approval prompts and the subagent view. Move to muse exec in CI only once you have a test command that gates the pipeline independently of the agent’s exit code. Keep the approval mode at on-request for your own repositories and switch to untrusted for anything that came from outside. Read every hook and MCP server you enable, because neither is contained by the sandbox. And export the log for any run that touched production-adjacent state — a deterministic hash of a session is the cheapest audit artefact you will ever produce.

Where this sits against Claude Code, Codex CLI and the rest of the field is a separate question with its own answer, and we take it up in our head-to-head comparison of Muse Code, Claude Code and Codex CLI, publishing this week. If you would rather have the evaluation run for you — harness selection, sandbox posture, CI wiring and the governance that has to surround an agent with write access — that is the shape of our AI and digital transformation engagements.