mu

A small control plane for a crew of AI coding agents working in parallel. Agents run in multiplexer panes you can attach to. Work is a task DAG in SQLite. Each agent gets its own git worktree.

• Parallel work that does not collide. Per-agent git worktrees and a task DAG with blocks edges keep agents out of each other's way.
• State that outlives a pane. One SQLite DB holds agents, tasks, owners, notes, and worktrees. An append-only ops log records every change, so mu log --group <group> shows one action and mu rebuild replays the whole history.
• Exact control of pi agents. mu's pi extension serves a control socket inside each agent, so send, state, wait, and abort are exact, locally and over ssh. The pane stays pi's normal TUI.
• One wait. mu wait blocks until the first event you own (closed, settled, needs you, dead, stalled) and prints one JSON result with a resume command. In pi, the extension runs it for you, so an orchestrator keeps driving until nothing is owed.
• Delegates without a pane. A mu_delegate call is a fresh-context helper recorded as a task with a durable id. With no tmux or herdr it runs as a child pi.
• A capped skill. One mu skill (under 600 words) and twelve short recipes, checked by an eval matrix (tools/eval). mu --help holds the rest.

Every read path has --json, and every change goes through a typed CLI verb. See What mu is not.

Status: 4.0, a breaking rewrite for agent callers with its own DB. It never imports a 3.x DB; open work moves one workstream at a time. Coming from 3.x? Read Upgrade from 3.x to 4.0 before you install.

Install

npm i -g @mu-crew/mu
pi install npm:@mu-crew/mu   # extension (control socket, mu_delegate), the mu skill, recipe prompts
mu doctor

To drive mu from another agent CLI (claude-code, codex, cursor-agent), install the skill with npx skills add mu-crew/mu instead of the pi package. Read Run mu with other agent CLIs first: pin which mu the harness runs, and see what works without pi.

You need:

• Node 22.12–26 (see .nvmrc).
• tmux ≥ 3.0 or herdr for agents. mu doctor reports which one is active. Without either, task verbs and pi's mu_delegate still work (a delegate runs as a child pi).
• pi, or another agent CLI.
• git on PATH for --worktree.

murmur is optional for pi agents. Non-pi agents on tmux need it for state: without it their state is unknown, so a wait never sees them finish and stall detection never fires. On herdr, herdr reports state.

Updating, keeping 3.x runnable beside 4.0, and running from a checkout: How to upgrade mu.

Quick start

Run this inside tmux or herdr, in a git repository:

mu workstream init auth                             # every verb below names it with -w
mu task add design_auth -w auth --title "Design auth" --impact 80 --effort-days 2
mu task add build_auth  -w auth --title "Build auth"  --impact 80 --effort-days 5 --blocked-by design_auth
mu agent spawn worker-1 -w auth --worktree
mu task claim design_auth -w auth --for worker-1
mu agent send worker-1 -w auth --fresh 'Do task design_auth. Close it with evidence.'
mu wait task:design_auth -w auth   # one JSON result; exit 7 = worker needs you
mu workstream teardown auth                         # preview (rev=<n>); apply with --if <n>

For one helper, ask pi to delegate (mu_delegate ships in the pi package), or spawn into the reserved scratch workstream: mu agent spawn scout-1 -w scratch.

Run mu with no arguments for the read-only dashboard. It has five tabs (Overview, Tasks, DAG, Agents, Log), with what needs a human on top: a dead or stalled worker, one waiting on a permission or on input, a human-needed task, a refused or failed delegate call.

Ultrathink, the mu way

Long agent runs fail in two ways: the agent stops at 35 of 50 items and calls it done, and it grades its own work generously. The fix is to take the plan out of the agent's head, fan the work out to fresh agents, and have other agents try to refute each result before it counts. Claude Code's ultracode does this with a hidden script. mu does it in the open:

• The plan is the DAG. Every unit, review gate, finding and round is a task before an agent spawns. mu state shows 35 of 50 done, so nobody can declare victory early.
• Findings are tasks. A reviewer records each problem as a task in triage (findings), and it blocks the review until someone accepts it as work or closes it rejected or duplicate. The graph holds the whole review.
• Checks are calls. Refuters, claim checkers and judges are delegate calls: fresh agents, ideally on another model, whose verdicts land on the task they judged. A 50-unit run adds about 50 units, 50 review gates and the findings that survive, not a task per check.
• Every agent is attachable. Attach to any worker, reviewer, or judge in its pane mid-run and steer it.
• Nothing lives only in a context window. Verdicts, evidence, and stop rules are task notes. The run survives compaction, crashes, and a new orchestrator.

Not every review needs a record. Reviewing someone's PR or a doc runs as delegates only: findings come back in their answers, and nothing enters your workstream's task graph. Each call is still a task in scratch (its prompt and answer), which syncs like any task.

Ask your orchestrator to ultrathink a job, and it follows the orchestrator loop: every unit, review and round is a task, and checks are calls. The recipes it composes you can also use on their own:

| Recipe | Shape | | ------ | ----- | | orchestrator-loop | dispatch, wait, merge; also sweeps and loops until a stop rule holds | | adversarial-review | a review gate per unit: a fresh agent tries to reject it before it ships | | findings | reviewers record findings, one refuter call per finding, report from the graph | | tasks-or-calls | refuters, judges and checkers as delegate calls | | course-correct | a periodic look at whether a long job is on course | | move | move a 3.x workstream into 4.0 |

In pi, the package adds them as commands: /ultrathink <job>, /mu-research <question>, /mu-review [target], /mu-refute <scope>, /mu-tournament <task>, /mu-rules-audit [target], /mu-debug <symptom>, /mu-sweep <change>, and /mu-until <stop rule>.

All recipes, including the orchestrator loop and remote workers, are in skills/mu/recipes/.

What mu is not

• Not a hidden subagent. Every agent, including a one-off mu_delegate helper, is an ordinary agent you can steer, abort, or keep talking to, in a pane you can attach to (with no tmux or herdr, a child pi and a task record). That costs a pi process per agent; for many tiny calls a hidden subagent is lighter. See the comparison.
• Not a workflow engine. No DSL, no hidden plan, no script runner. The plan is the task DAG; recipes are instructions an agent follows, and every step is a CLI verb.
• Not a model router. mu does not pick models, thinking levels, or tools. Pass them in the spawn command (--cli pi_big).
• Not a chat bus. Agents coordinate through task notes, claims, and the ops log, not messages to each other.
• Not a daemon or a service. No background process, config file, web UI, or RPC. State is one SQLite file; sync rides on ordinary commands.
• Not a test runner or a judge. --evidence records what an agent observed; checking it is the orchestrator's job, and the recipes say how.

The full list, with reasons: VISION § What it is not and ROADMAP § Anti-feature pledges.

Documentation

• Getting started: the first workstream, end to end. Start here.
• User guide: how-tos for dispatch, remote workers, sync, and recovery.
• skills/mu/SKILL.md: what an orchestrating agent reads. skills/mu/recipes/ holds the recipes it points to, such as remote workers.
• ARCHITECTURE.md and docs/architecture/: the module map and deep dives.
• VISION.md: the design pillars. ROADMAP.md: what is next and what is rejected.
• VOCABULARY.md: canonical terms.
• CHANGELOG.md: release notes.

mu <verb> --help is the reference for every flag.

License

MIT. Part of mu-crew. Written mostly by AI coding agents, with a human reviewing what ships.