--- name: mu description: Manage AI agents in tmux panes — from a single off-the-cuff helper to a persistent crew coordinated through a built-in task graph. Use when the user asks to "create/spin up a subagent to X", "run X in the background", "do this in parallel", "use one subagent per X to do Y", "kick off a helper to watch/investigate/draft X", or to spawn, send work to, observe, or coordinate one or many agents — especially work you'll keep talking to, long-lived agents, background tasks, or anything that benefits from a dependency graph and parallel-track detection. For zero-ceremony single helpers use the reserved `scratch` workstream; for one-shot "fire and get a result back" prefer pi-subagents. --- # mu — Multi-agent orchestration `mu` manages long-lived AI agents in tmux panes, coordinated by a SQLite task DAG at `/mu/mu.db`. **Trust `mu --help` / `mu --help` over this skill.** Verbs not in `--help` do not exist. ## Output + JSON shapes Default output: textual card on stdout plus a `Next:` block. Read both. `--json` exists on every verb: - Success: one stdout object. - Collection reads (`task list`, `workspace commits`, `archive search`, ...): `{items: T[], count: number}`. - Singletons keep named fields. - `mu sql --json`: bare array rows. - `mu log --tail`: NDJSON (one object per line). - Errors: `{error,message,nextSteps,exitCode}` on stderr. - Validation errors also include structured `usage`. - **`nextSteps` survives in JSON**. `mu task wait --first --json` puts the cherry-pick command in `.nextSteps[0].command`. ## Vocabulary - **workstream** — unit of organization; tmux session `mu-`. - **agent** — named worker in a tmux pane (you may be one). - **task** — DAG node with mandatory `impact` (1–100) and `effort_days`. Status: `OPEN`, `IN_PROGRESS`, `CLOSED` (satisfies `--blocked-by`), `REJECTED` (terminal won't-do; still blocks), `DEFERRED` (parked; still blocks). - **claim / release** — atomic take/clear of `tasks.owner`. - **free** — mark the *agent* available (`mu agent free`); pane untouched. **Release is about the task; free is about the agent.** - **note** — append-only task context; survives sessions. - **track** — independent DAG subtree; don't spawn more agents than ready tracks. - **workspace** — per-agent VCS copy under `/workspaces///`. ## When to use mu Use mu for multi-phase work, review-gated work (`implement → review → address → ship`), parallel audits, implementation/reviewer splits, and anything that must survive context compaction via task notes. Do **not** use mu for tiny one-file edits, one-off local inspection, or single-context work where durable coordination adds ceremony. ### Off-the-cuff helpers (the `scratch` workstream) Want a sub-agent you'll **keep talking to** — "create a subagent to X", "run X in the background", "one subagent per X to do Y" — without a crew or task DAG? Spawn into the reserved `scratch` workstream. No `mu workstream init`; it auto-creates and is task-less by design. ```bash mu agent spawn helper-1 -w scratch # auto-creates mu-scratch mu agent send helper-1 'Investigate X. Report findings.' mu agent read helper-1 -n 50 # check at a natural pause, not in a loop mu agent close helper-1 -w scratch # done ``` - **Background watcher:** send the task, then `mu agent wait --first` to block until it finishes (busy → idle) instead of a `sleep` loop; re-nudge with another `send` (e.g. `'run again'`). - **Fan-out, one per unit:** loop `mu agent spawn dep-$pkg -w scratch --workspace`, then `mu agent wait dep-core dep-cli dep-web` (all) or `--any` to react to whichever finishes first. Add `--workspace` whenever a helper will edit/build/test a shared repo (see "Workspaces prevent trampling"); skip it for read-only helpers. `mu state -w scratch` watches them all. If a helper wedges at `needs_input` right after spawn, it's likely pi's project-trust prompt. Spawn with `--command 'pi --approve'` (or set `MU_PI_COMMAND="pi --approve"`) so agents don't block on it. **Escalate off `scratch`** the moment helpers have dependencies (B needs A) or you want gated review → real `mu workstream init` + task DAG. Need just one focused answer, no follow-up → `pi-subagents` (one-shot, returns a result). `scratch` is the middle: "fire, but keep the channel open." ## Mental model ### Workstreams, DAGs, tracks One workstream = one tmux session named `mu-`. Every agent is a pane in that session. DB rows are partitioned by `workstream`. One edge type: `blocks`. `mu task block A --by B` means **B blocks A**. Built-in views: `ready`, `blocked`, `goals`. Bare `mu` shows parallel tracks with automatic diamond-merge: goals sharing a prerequisite collapse into one track. ### Workspaces prevent trampling If an agent may edit/build/test/generate artifacts while another agent is active in the same repo, spawn with `--workspace`. Keep the main checkout for orchestration. Two builds in one checkout corrupt each other's artifacts. Workspaces auto-detect jj/sl/git; non-VCS uses `cp -a`. They are auto-freed on `mu agent close` **iff clean**: no uncommitted changes and no commits since fork. Non-clean close fails with `WorkspacePreservedError`; then use `mu workspace free ` or `mu agent close --discard-workspace` (lossy). Between waves: - `mu workspace refresh ` rebases onto fresh main without killing LLM context. - `mu workspace recreate ` = free + create for fresh single-purpose workers; `--force` discards dirty edits. - `mu workspace commits ` lists since-fork commits for cherry-picking. Claim/send warn when a target workspace is ≥10 commits behind main; refresh first or pass `--strict-staleness` in scripts. ### Agent names Use roles: `worker-1`, `worker-2`, `reviewer-1`, `scout-1`, `auditor-1`, `planner-1`. Smallest unused suffix. Avoid human names. ### Task note contract End every delegated task with a note containing the applicable fields: ```text FILES: paths inspected/changed (line ranges if precise) COMMANDS: commands run + exit codes FINDINGS: what you observed DECISION: what you chose, and why NEXT: follow-on tasks VERIFIED: tests/checks/output ODDITIES: weird things not acted on ``` Then close with grounding: ```bash mu task close -w --evidence "tests pass: cargo test exit 0" ``` Future agents can reconstruct context via `mu task notes `. ## Orchestrator loop Every turn: 1. `mu state -w ` — read agents, IN_PROGRESS, ready tasks, parallel tracks. 2. Spawn at most one agent per independent ready track. 3. **Claim before sending — even one-shot reviewers/scouts.** `mu task claim -w --for --evidence "..."`. If no task exists, `mu task add` first; include initial context with `--note 'REPRO: ...\nSCOPE: ...'` when the title alone is not enough. Agent status is noisy; task ownership is durable and waitable. 4. Send terse instructions: task id, files/notes to read, workspace path, validation command, scope guards, task note contract. 5. End with a loud final-action block: ```text ⚠️ FINAL ACTION git commit -am '...' THEN mu task close -w --evidence '...' ``` 6. `mu task wait ... --first --any --json --on-stall exit`. 7. Cherry-pick the closed worker's **new** commit(s), verify, return control. Do not barrier or loop in shell. 8. Repeat from `mu state`. ## Dispatch rules that prevent real failures - **Pipeline cherry-picks; don't barrier.** One wait, one cherry-pick, one verify, return control. Do not wait on an umbrella task for the whole wave; that hides partial progress. - **Use `--on-stall exit` in non-interactive flows.** Default wait warns on stalled alive workers and keeps polling. Exit 7 = `STALL_DETECTED`; exit 6 = `REAPER_DETECTED` (dead pane) and wins if both happen. - **Cherry-pick worker commits onto main; don't merge.** Stale branches can drag re-reverts. - **Cherry-pick only new shas.** `workspace commits` lists since fork; track what you've already integrated. Don't replay the whole worker range each time. - **Bucket fix waves by file cluster, not severity.** Two workers editing one file create merge conflicts. - **Refresh/recreate workspaces between waves.** The `behind` column in `mu workspace list` shows stale-parent risk. - **Cross-workstream wait/claim:** pass qualified refs `/`. For `claim --for A/worker-1` on a task in B, the agent stays in A; only task ownership crosses. - **Recover idle agents:** `mu agent show -n N`; then send a retry or `mu task release ` (bare release reopens IN_PROGRESS). Idle threshold: `MU_IDLE_THRESHOLD_MS`, default 5m. - **Recover wedged tool subprocesses:** `mu agent kick ` sends SIGINT to the pane TTY foreground process group. Escalate with `--signal SIGTERM` / `SIGKILL`. It refuses when the foreground is the wrapping CLI; use `mu agent close` then. - **Use `mu agent send`; never raw `tmux send-keys `.** mu uses bracketed paste so `/`, `?`, `f`, etc. are delivered as text instead of agent-TUI keybindings. - **Prompt quoting:** single-quote prompts containing `$VAR`, `$(...)`, backticks, or `!history`, or use a quoted heredoc. Example wait/cherry-pick skeleton: ```bash res=$(mu task wait t1 t2 t3 -w ws --any --first --json \ --timeout 600 --on-stall exit) worker=$(jq -r .firing.owner <<<"$res") sha=$(mu workspace commits "$worker" -w ws --json | jq -r '.items[0].sha') git cherry-pick "$sha" && npm test ``` ## Universal flags - `-w, --workstream ` resolves explicit > `$MU_SESSION` > current tmux session minus `mu-` > error. For entity verbs it is a scope check; for pickers it selects which workstream. - Qualified refs `/` skip `-w`; mismatched `-w` errors. Bare ambiguous names raise `NameAmbiguousError` (exit 4) with one-paste fixes. - `--evidence "text"` on task `claim/close/open/release`; recorded verbatim in emitted events. - `--json` for composition; `nextSteps` survives. ## CLI overview (only gotchas; use `--help` for full syntax) - **Workstream:** `init`, `list`, `destroy` (auto-snapshot; `--archive