muse

v1.4.0 · MIT · open source

muse, the Claude Code plugin that delegates bulk coding workand has a supervisor that actually checks it.

muse types, Claude judges. Push repetitive work to cheap Muse Code workers in isolated git worktrees. A Claude supervisor reads each patch, runs your acceptance check itself, and sends the worker back until the final check passes.

  1. /plugin marketplace add jellologic/claude-code-muse
  2. /plugin install muse@claude-code-muse

Then start a new session (or /clear) so /muse:* registers, and run muse login once. Needs the muse CLI, git, Python 3.9+ and Claude Code.

View on GitHub How it works 
/muse:delegate Create tests/test_ratio.py covering
  percent() in ratio.py. Do not modify ratio.py.
  Check: python3 -m pytest tests/test_ratio.py -q

Verdict: accept — 1 round of 3. The supervisor
ran the check itself and it passed.
Check: python3 -m pytest tests/test_ratio.py -q
  → exit 0, 3 passed, 1 xfailed
Patch not applied — your call.
Real output, quoted from the project README.
  • 625offline checks, run on Linux and Windows CI
  • 28/28planted bugs killed by the mutation harness
  • ~625always-on tokens, under a 750 ceiling
  • 7slash commands, all opt-in

01 · How it works

One supervisor, one task, looped until the check passes

Each delegated task is owned end to end by a supervisor agent. The worker does the typing; the supervisor decides whether what it typed is right. The loop is capped at max_rounds (3 by default) so a confused worker cannot run up a bill.

The loop: plan, then muse run, read patch, verify and revise repeat inside one supervisor until the check passes, then a verdict. one supervisor, one task plan muse run read patch verify revise verdict until right · at most max_rounds The loop: plan, then muse run, read patch, verify and revise repeat inside one supervisor until the check passes, then a verdict. one supervisor, one task plan muse run read patch verify revise verdict until right

  1. Plan

    A brief that names the exact files, says what must not change, and gives a runnable acceptance check. /muse:fleet splits a bigger job into disjoint tasks.

  2. muse run

    A Muse Code worker edits in its own git worktree on a throwaway branch, created beside the repository. The worktree is scanned for credentials first.

  3. Read patch

    The supervisor reads the diff the worker produced, not the worker's summary of it.

  4. Verify

    The supervisor runs the acceptance check itself and the exit code is recorded. That is the evidence, not the worker's confidence.

  5. Revise

    On a defect, the worker is sent back with specific problems, in the round where fixing is still cheap.

  6. Verdict

    accept, revise or reject, plus a patch path. Nothing is applied to your repository.

02 · Why a supervisor

Completed is not accepted

Cheap delegation fails in exactly one place: a model grading its own homework.

A reviewer that can only file a report is strictly weaker than one that can re-prompt the author while fixing is still cheap. So the grading moves into the agent that owns the task, and the cheap model's last word is never the deliverable.

finish --verdict accept refuses unless the final check passed and ran against the tree being harvested, so a green check from before something touched the worktree does not certify the patch that ships. --accept-unverified "<reason>" is the deliberate way past it; the reason is recorded and /muse:status prints it.

Two words the design depends on keeping apart
WordMeans
completedthe worker stopped
accepta supervisor ran a check and the final one passed

/muse:status flags ACCEPTED WITHOUT AN EXECUTED CHECK and ACCEPTED WITHOUT A PASSING FINAL CHECK, so an unproven patch cannot pass as a proven one.

03 · Commands

Seven slash commands, every one opt-in

No command is invoked by the model on its own. The plugin also puts seven shims on PATH (muse-task, muse-fleet, muse-ask and friends) so the same command runs in a supervisor, a workflow or your own terminal.

CommandDoes
/muse:delegate <task>One task, supervised end to end: run, verify, revise, verdict
/muse:fleet <job>Decompose a job and fan out, one supervisor per task
/muse:ask <question>One question or one contained edit, no worktree, answer on stdout
/muse:statusWhat every task did, and whether a check actually ran
/muse:modelWhich contributor model delegation will use
/muse:doctorWhether this machine can delegate, and what would break, with a fix on every failing line
/muse:cleanupReap worktrees, branches and artifacts a run left behind (dry run unless --yes)

04 · Safety

Guards that are enforced, not described

Every guard in the offline suite is negative-controlled: broken on purpose and confirmed to go red, because a check that inspects nothing passes exactly like one that found nothing.

  • It refuses to send your credentials

    Before a worker spawns, the worktree is scanned (after seeding, so it sees the .env you asked it to copy) and delegation is refused on a PEM private-key block, an AWS key id, or a GitHub, Slack, Stripe or Anthropic-format token. Findings record file, line and kind, never the matched text. /muse:doctor --scan runs it on demand.

  • The supervisor cannot write

    The supervisor agent has no Write or Edit tool, and a PreToolUse hook denies its Write, Edit and NotebookEdit calls and any Bash beyond the muse shims, read-only git, readers and the recorded check. A SubagentStop hook blocks it from stopping while its task has no verdict.

  • Worktree isolation

    Workers run with --yolo, defensible only because the blast radius is a throwaway worktree on a throwaway branch, outside your repository. The drivers refuse a dirty working copy, and a worktree root inside the repo is refused.

  • Nothing applied by default

    No command applies a patch. Runs stop at a verdict and a patch path. /muse:cleanup is a dry run unless you pass --yes, and skips unfinished tasks unless you pass --all.

The sharpest edge: your acceptance check runs on the host, with your privileges. In the fleet path the check is written by a model, so the workflow prints every planned check before running it. Read those the way you would read a command you are about to type. See SECURITY.md.

05 · Fit

When to use it, and when not to

Fan-out pays when tasks are independent and mechanical. The deciding question: could a competent contractor do this task knowing only this one prompt and the repo?

Use it for

  • A test file per module
  • One migration pattern applied repo-wide
  • Type hints across a package
  • Bulk lint fixes
  • Tasks partitioned by file, each with a runnable check

Skip it for

  • One coherent change threaded through many files: that is one edit, not N
  • Debugging, which needs the whole picture
  • Anything needing a design decision: there is no oracle
  • Several tasks that rewrite the same file, or conflict magnets like lockfiles and registries
  • A task with no runnable check: review that one by hand
  • Proprietary code on the contributor tier: pin muse-spark-1.3 or keep it local

06 · Configuration

Five settings, prompted at install

Each default is exactly what the plugin did before configuration existed, so skipping every prompt changes nothing. A set-but-invalid value is refused rather than silently replaced, every flag still overrides for one run, and /muse:doctor shows where each value came from.

OptionDefaultWhat it controls
default_effortlowReasoning effort every round starts at (none to max). Higher costs more per task; lower means more revision rounds.
max_rounds3Revision rounds per task, bounded 1 to 10. The runaway-cost breaker.
worktree_rootemptyWhere worktrees go. Empty means beside the repository; a path inside it is refused.
refuse_on_secretsonRefuse to delegate a tree containing a credential. Turn off only where credential-shaped content is entirely test fixtures.
default_modellatest-contributorResolves the newest contributor-tier model from muse's catalog at run time. Pin muse-spark-1.3 for proprietary code.

07 · FAQ

Questions people ask

How do I delegate coding tasks from Claude Code to a cheaper model?

Install the muse plugin, start a new session, run muse login once, then run /muse:delegate with a brief that names the exact files, says what must not change and gives a runnable acceptance check. A Muse Code worker makes the edit in its own git worktree, and a Claude supervisor runs the check itself and sends the worker back until the final check passes. For a batch of independent tasks, /muse:fleet decomposes the job and runs one supervisor per task.

What is Muse Code, and how does it compare with Claude Code?

Muse Code is the coding agent behind Meta's Muse Code API, driven through the muse command-line tool. Here it does not replace Claude Code: muse does the typing, and Claude Code plans the work, reviews each patch and runs your acceptance check. The plugin needs muse on your PATH and credentials from muse login. By default delegated work uses the newest contributor-tier model from muse's own catalog; you can pin a full-rate model such as muse-spark-1.3 instead.

Does the plugin send my code or secrets anywhere?

Prompts, the files the worker reads and its patches go to Meta's Muse Code API under the model you selected, and contributor-tier models state that content may be used for product improvement. Nothing is sent anywhere else: there is no telemetry, no analytics and no network call in the plugin outside the muse CLI. Before a worker starts, the worktree is scanned and delegation is refused on a PEM private-key block, an AWS key id, or a GitHub, Slack, Stripe or Anthropic-format token. For proprietary code, pin muse-spark-1.3 at full rate or do not delegate it.

Can a Claude Code subagent use a different, cheaper model?

A Claude Code subagent can run on a smaller Claude model, but it still types the code itself. muse routes the typing to a different model entirely: a Muse Code worker edits in an isolated git worktree, while the muse-supervisor subagent (on Opus) reads the patch, runs your acceptance check itself and re-prompts the worker with specific defects. A PreToolUse hook denies the supervisor's own writes, and a SubagentStop hook blocks it from stopping while its task has no verdict.

Does it apply patches automatically?

No. No command applies a patch: every run stops at a verdict and a patch path, because an accepted patch is still a patch you have not read. Worktrees and branches stay until you remove them with /muse:cleanup, which is a dry run unless you pass --yes.

Does it work on Windows?

The free offline suite runs in CI on Linux under Python 3.9, 3.11 and 3.13, and on Windows under Git Bash as a blocking job; development is on macOS. You need the muse CLI, git, Python 3.9 or later and Claude Code.

What is the difference between completed and accepted?

Completed means the worker stopped. Accept means a supervisor ran a check and the final one passed. finish --verdict accept refuses unless the final check passed against the tree being harvested; --accept-unverified with a reason is the deliberate way past it, and /muse:status prints that reason.

Does it save Claude Code tokens?

It moves the typing off Claude. The Muse Code worker generates the code, and Claude spends its tokens reading the patch and running the check rather than writing boilerplate. The plugin itself adds about 625 always-on tokens, against a 750-token ceiling the project holds itself to; the seven slash commands are opt-in, and the hooks add context only when they have something to report.