# mu — Usage Guide A practical, copy-pasteable tour of mu. Terms are canonical — see [VOCABULARY.md](VOCABULARY.md); the canonical verb list is `mu --help`, with the gotchas in `## CLI overview` of [skills/mu/SKILL.md](../skills/mu/SKILL.md). > **Status:** 1.0 (pre-release). ~60 typed verbs across 8 namespaces > (`workstream`, `agent`, `task`, `workspace`, `log`, `archive`, `me`, > `db`) plus bare top-level verbs (`state`, `doctor`, `sql`, `undo`, > `sync`, `rebuild`). Every verb accepts `--json` (one exception, > `mu agent attach`). Schema v9. See [CHANGELOG.md](../CHANGELOG.md). **In a hurry? Start at [§ 0. Common scenarios](#0-common-scenarios).** *If anything below disagrees with `mu --help`, trust `mu --help`.* --- ## Table of contents 0. [Common scenarios (start here)](#0-common-scenarios) 1. [Setup](#1-setup) 2. [Get oriented (`mu doctor`)](#2-get-oriented) 3. [Create a workstream (`mu workstream init`)](#3-create-a-workstream) 4. [Plan some work as a DAG (`mu task add`)](#4-plan-some-work-as-a-dag) 5. [See the graph (dashboard + state API)](#5-see-the-graph-dashboard--state-api) 5b. [The TUI dashboard (interactive)](#5b-the-tui-dashboard-interactive) 6. [Spawn a crew (`mu agent spawn`)](#6-spawn-a-crew) 7. [Watch the crew live (`tmux attach`)](#7-watch-the-crew-live) 8. [Send work to an agent (`mu agent send`)](#8-send-work-to-an-agent) 9. [Read what an agent did (`mu agent read`)](#9-read-what-an-agent-did) 10. [The claim protocol from inside a pane (`mu task claim`)](#10-the-claim-protocol--from-inside-an-agents-pane) 11. [Drop notes (durable context) (`mu task note`)](#11-drop-notes-durable-context) 12. [Close out a task](#12-close-out-a-task) 13. [The SQL escape hatch (`mu sql`)](#13-the-sql-escape-hatch-is-your-friend) 14. [Recovery scenarios](#14-recovery-scenarios) 15. [Cleanup](#15-cleanup) 15.5. [Archives — named markers pinning the ops log](#155-archives--named-markers-pinning-the-ops-log) 15.6. [Multi-machine sync](#156-multi-machine-sync) 16. [One-shot demo script](#16-one-shot-demo-script) 17. [Mental model in three sentences](#mental-model-in-three-sentences) 18. [What's NOT in mu](#whats-not-in-mu-and-how-to-work-around-it) 19. [Where to go from here](#where-to-go-from-here) 20. [Multiplexer backends (tmux and herdr)](#20-multiplexer-backends-tmux-and-herdr) --- ## 0. Common scenarios Six worked paths, every command run live. Output is verbatim (colour stripped). Set `MU_DB_PATH=/tmp/mu-play.db` first if you want to try them without touching your real registry. ### 0.1 First 5 minutes Init a workstream, plan two tasks with a dependency, see what's ready. ```bash mu workstream init auth mu task add design -w auth --title "Design auth module" --impact 80 --effort-days 2 mu task add build -w auth --title "Build auth module" --impact 80 --effort-days 5 --blocked-by design mu task next -w auth mu task tree build -w auth ``` ``` Created workstream auth (tmux session mu-auth) Next: Attach the tmux session : tmux a -t mu-auth Plan tasks : mu task add -w auth --title "..." --impact 50 --effort-days 1 Spawn an agent : mu agent spawn -w auth See state : mu state -w auth Added task design (workstream=auth, impact=80, effort=2) Added task build (workstream=auth, impact=80, effort=5) blocked by: design ┌────────┬────────┬────────────────────┬────────┬────────┬──────┬───────┐ │ name │ status │ title │ impact │ effort │ ROI │ owner │ ├────────┼────────┼────────────────────┼────────┼────────┼──────┼───────┤ │ design │ OPEN │ Design auth module │ 80 │ 2 │ 40.0 │ — │ └────────┴────────┴────────────────────┴────────┴────────┴──────┴───────┘ Tree of build (blockers below; --down for dependents) build OPEN Build auth module └── design OPEN Design auth module ``` `build` is absent from `mu task next` because `design` blocks it. Close `design` and `build` becomes ready. Details: [§ 3](#3-create-a-workstream), [§ 4](#4-plan-some-work-as-a-dag). ### 0.2 The dispatch loop: spawn, claim, send, wait, close ```bash mu agent spawn worker-1 -w auth --cli sh # --cli pi for a real agent mu task claim design -w auth --for worker-1 mu agent send worker-1 -w auth 'Design the auth module, then: mu task close design --evidence "..."' mu task wait design -w auth --timeout 60 # blocks until CLOSED mu agent close worker-1 -w auth ``` ``` Spawned worker-1 (sh) in window worker-1 of mu-auth, pane %88 Claimed design for worker-1 (OPEN → IN_PROGRESS) Next: Drop a note (single-quote to defer shell expansion) : mu task note design 'FILES: ...\nDECISION: ...' -w auth Close with grounding : mu task close design --evidence "..." -w auth Release if blocked : mu task release design -w auth sent 23 bytes to worker-1 all-of 1 reached CLOSED in 4094ms ✓ design (CLOSED) Closed worker-1 ``` Exit codes from `mu task wait`: `0` met, `5` timeout, `6` the owning pane died, `7` stalled (with `--on-stall exit`). See [§ Wait exit codes](#wait-exit-codes-mu-task-wait). `mu agent send` verifies delivery. If it prints `warning: ... was NOT submitted`, the text is sitting unsubmitted in the pane — the agent has not seen it. That is the failure mode `exit 0` used to hide; check before you wait on the task. ### 0.3 Laptop ↔ devserver Same `MU_SYNC_DIR` on both machines. No export step, no import step, no sync verb in the loop. ```bash # both machines, in your shell rc export MU_SYNC_DIR=$HOME/Sync/mu # laptop mu workstream init app mu task add auth_fix -w app -t "Fix the auth redirect" -i 80 -e 2 # devserver — the ordinary command already ingested it mu task list -w app mu task close auth_fix -w app --evidence "shipped in #412" # laptop mu task show auth_fix -w app ``` ``` ┌──────────┬────────┬───────────────────────┬────────┬────────┬──────┬───────┐ │ name │ status │ title │ impact │ effort │ ROI │ owner │ ├──────────┼────────┼───────────────────────┼────────┼────────┼──────┼───────┤ │ auth_fix │ OPEN │ Fix the auth redirect │ 80 │ 2 │ 40.0 │ — │ └──────────┴────────┴───────────────────────┴────────┴────────┴──────┴───────┘ Closed auth_fix (OPEN → CLOSED) evidence: shipped in #412 auth_fix — Fix the auth redirect workstream : app status : CLOSED ... Notes (1) 2026-08-02T05:49:15.361Z worker-2 CLOSE: shipped in #412 ``` **Both machines edit at once.** Merges are per-FIELD, so different fields of the same task both survive: ```bash # laptop # devserver mu task update t1 -w app --impact 95 mu task close t1 -w app ``` ``` # both machines, after both have synced: t1 — Concurrent demo status : CLOSED impact : 95 ``` Same field on both machines: the newer HLC wins, silently. Peer status is `mu sync`; a torn transfer is `mu sync --repair `. Full section: [§ 15.6](#156-multi-machine-sync). ### 0.4 I made a mistake Every user-visible action is one **group** of ops. Find it, preview, apply. ```bash mu task update build -w auth --impact 5 # oops mu undo # what can I undo? mu undo 6380dd3d # preview (dry run) mu undo 6380dd3d --yes # apply ``` ``` mu undo — most recent undoable action: 6380dd3d task.update — 1 op recent groups (newest first): * 6380dd3d task.update — 1 op 1abb5038 task.add — 2 ops 4f93f1df task.add — 1 op 70af8fb8 workstream.init — 1 op mu undo 6380dd3d — would revert task.update restore task auth/build impact=80 updated_at=2026-08-02T05:49:34.545Z (dry-run; rerun with --yes to apply) Undid 6380dd3d (task.update) task auth/build impact=80 updated_at=2026-08-02T05:49:34.545Z 1 row change(s), recorded as group 3814ed17 This undo is itself undoable: mu undo 3814ed17 --yes ``` The undo is itself a group — `mu undo 3814ed17 --yes` is redo. Any unique prefix of a group id works. Undo reverts ROWS: killed panes and freed workspace dirs do not come back. See [§ Undoing one action](#undoing-one-action-mu-undo). ### 0.5 Something looks wrong ```bash mu doctor # exit 0 healthy, 5 on drift mu doctor --deep # full rebuild + field diff; slower ``` ``` mu doctor environment tmux : ok (tmux 3.7b) $TMUX : set $TMUX_PANE : %21 $MU_SESSION : auth db path : /tmp/mu-play.db schema : ok (10 tables) schema_version : 9 journal_mode : wal foreign_keys : on workstream current : auth state (workstream=auth) agents : 0 tasks : 2 (ready 1, blocked 1, in-progress 0) ops rows : 1 ghosts : none orphan panes : 0 fleet db-vs-sync : ok MU_SYNC_DIR not set (no sync configured) db-filesystem : ok DB is on local (0x1021994) name-case : ok no case-colliding workstream names ops log drift (shallow) : ok every live row has ops (1ms) — run `mu doctor --deep` for the full rebuild diff ``` **On drift**, `--deep` names the exact table, key and field: ``` ops log drift : FAIL 1 divergence(s) (16ms) tasks auth/build.title: live=TAMPERED log=Build auth module ``` Do not rebuild reflexively — which side is right depends on the cause. In order: ```bash mu db backup /tmp/mu-drift-evidence.db # 1. preserve the evidence mu rebuild /tmp/mu-rebuilt.db # 2. materialize what the log believes MU_DB_PATH=/tmp/mu-rebuilt.db mu sql "SELECT local_id, title FROM tasks" # 3. compare ``` Then report it: drift is a capture/apply bug, and the named table/key/field is the reproduction. See [§ What to do when drift is reported](#what-to-do-when-drift-is-reported). ### 0.6 Upgrading from mu 0.4.x `mu` refuses to open a pre-v9 DB (`SchemaTooOldError`, exit 4) and leaves the file alone. A sidecar, `scripts/migrate-to-1.0.ts`, imports a pre-1.0 DB into a fresh v9 one; you run it once, by hand, against a copy. Workstreams, tasks, edges and notes come across; agents, workspaces and ownership do not. Full recipe and flags: [scripts/README.md](../scripts/README.md). Summary here: [§ 15.7](#157-coming-from-mu-04x). --- ## 1. Setup From npm (the common path): ```bash npm install -g @martintrojer/mu mu --version # → the current version ``` Update later via `npm install -g @martintrojer/mu@latest`. From a local checkout (when hacking on mu itself): ```bash npm install -g . # `prepare` script auto-builds; `mu` lands on $PATH mu --version # → the current version (see package.json) ``` To update the source-installed copy: pull from upstream, then `npm install -g .` from inside the checkout. The `prepare` script rebuilds before linking the new dist/. ### Install the bundled skill Mu ships a skill at `skills/mu/SKILL.md` that teaches the LLM running inside an agent pane how to use mu. The canonical install path is the [skills CLI](https://github.com/vercel-labs/skills), which auto-detects every supported agent (pi, claude-code, codex, opencode, cursor, ...) and installs into the right per-agent location: ```bash npx skills add martintrojer/mu # interactive: pick scope + agents npx skills add martintrojer/mu -g -y # global, no prompts (pi: ~/.pi/agent/skills/mu/) npx skills update mu # later, to refresh ``` Hacking on the skill itself? Point the skills CLI at your checkout so edits flow straight through: ```bash npx skills add ./skills/mu # local-path source format (symlinks) ``` Without the skills CLI, the skill is just a directory with a `SKILL.md` — symlink or copy it into the agent's skills dir. For pi: `~/.pi/agent/skills/mu/` (global) or `.pi/skills/mu/` (per-project). The cross-tool `~/.agents/skills/mu/` is picked up by pi and several others: ```bash # From an npm-global install mkdir -p ~/.agents/skills ln -sf "$(npm root -g)/@martintrojer/mu/skills/mu" ~/.agents/skills/mu # Or from a checkout ln -sf "$PWD/skills/mu" ~/.agents/skills/mu ``` ### For mu hackers: alias to the build output Fastest iteration when hacking on mu itself: ```bash npm install # deps only npm run build # produces dist/ alias mu="node $PWD/dist/cli.js" ``` See [README.md § Install](../README.md#install) for the full set of install patterns. mu requires a terminal multiplexer. tmux ≥ 3.0 is the complete backend and what the rest of this guide assumes; herdr is supported for topology but not yet for spawn/send/read (see [§ 20](#20-multiplexer-backends-tmux-and-herdr)). Make sure you're inside a session before proceeding: ```bash tmux # if you're not already in one ``` --- ## 2. Get oriented For a human at a terminal, bare `mu` is the home base: it launches the read-only TUI with every workstream on the machine loaded as tabs. Initial tab focus ladder: `$MU_SESSION` naming a loaded workstream → current tmux session named `mu-` → cwd inside a registered workspace → cwd at the VCS-derived project root of any loaded workstream (newest activity wins ties) → tab 0. With no workstream yet it prints help plus the start command: ```bash mu # Get started: mu workstream init ``` For scripts, agents, CI, and pipes, bare `mu` does NOT enter the TUI: when stdout is not a TTY it prints `mu --help`. Use explicit typed verbs and `--json` for the API surface: ```bash mu state -w --json MU_NO_TUI=1 mu # force the non-TTY/help path even in a terminal ``` Run `mu doctor` to check tmux + DB health — full annotated output in [§ 0.5 Something looks wrong](#05-something-looks-wrong). Two families of checks are the ones to know. **Mixed-fleet hazards** (the `fleet` section) — cheap, and every one is something you can fix before it costs you data: | Row | Means | | --- | --- | | `db-vs-sync` | **FAIL** if `MU_DB_PATH` is inside `MU_SYNC_DIR`. Never do this: a live WAL-mode SQLite DB is three files (`mu.db`, `-wal`, `-shm`) whose mutual consistency IS its durability, and a file-syncer copying them out of order — or resurrecting a peer's stale `-wal` — silently corrupts the database. mu syncs append-only per-machine **segments** so the DB file never has to travel. | | `db-filesystem` | **WARN** if the DB is on NFS/SMB/sshfs. WAL needs working advisory locks and a shared-memory file; network mounts provide neither reliably. Symptom is `database is locked` with no contention, or corruption with it. | | `name-case` | **WARN** if two workstream names differ only by case. They coexist on Linux but collide on macOS (APFS) and Windows, and a workstream name IS a tmux session name and seeds workspace paths — so a Mac joining the fleet sees one session where Linux sees two. | **Ops-log drift** (the `ops log` section) — is the projection still faithful to the log? Undo, archives, sync and history are all projections of the ops log, so a capture bug breaks all four at once, silently. Two tiers: ```bash mu doctor # shallow: every live row must have >=1 op. ~3ms. mu doctor --deep # full rebuild + field-level diff. ~0.6ms per op. ``` The default is shallow so `mu doctor` stays reflexive; the deep check rebuilds the whole log (~2.3s on a 1000-task DB). Shallow catches an uncaptured INSERT or DELETE and is blind to an uncaptured UPDATE (the row's key still has ops). Run `--deep` when you suspect something, in CI, or before a release. Either tier exits **5** on drift. ### What to do when drift is reported Drift names the exact table, key and field, e.g.: ``` drift : FAIL 2 divergence(s) (12ms) tasks demo/a.title: live=TAMPERED log=A tasks demo/a.impact: live=7 log=60 ``` **Do not rebuild reflexively.** Drift means the log and the tables disagree, and which side is right depends on the cause: - If **capture** missed a mutation, the LIVE tables hold real work the log never recorded — rebuilding would discard it. - If **apply** is lossy, the log is authoritative and a rebuild fixes it. So, in order: ```bash mu db backup /tmp/mu-drift-evidence.db # 1. preserve the evidence FIRST mu rebuild /tmp/mu-rebuilt.db # 2. materialize what the log believes # 3. compare the named keys in both files and decide which side is correct: MU_DB_PATH=/tmp/mu-rebuilt.db mu sql "SELECT local_id, title, impact FROM tasks" ``` Then report it. Drift is a capture/apply **bug**, not operator error, and the named table/key/field is the reproduction. ### Undoing one action (`mu undo`) Undo emits **inverse ops** for one **group** (one user-visible action). ```bash mu undo # what would I undo? lists recent groups + ids mu undo 1a2a94eb # preview the inverse (dry run) mu undo 1a2a94eb --yes # apply it ``` Three properties: - **Granular.** Only the rows that action touched. A cascade close wrote N task ops under one group, so undoing it reopens exactly those N. - **Itself an op.** The undo lands in its own group, so it syncs to peers and is **itself undoable** — that is redo: `mu undo --yes`. - **Refuses to clobber newer work.** If a later action changed the same fields, undo exits 4 and names the conflict: ``` WARNING: this group has been SUPERSEDED by later work. demo/a: impact was changed since by e04df0d5 (task.update) Undoing would DISCARD that newer work. Pass --force with --yes to do it anyway. ``` `--force` is the override, and it says what it destroys. Rows only: undo does not resurrect killed tmux panes or freed workspace directories. For whole-DB recovery from the log, use `mu rebuild `. Get the full command list: ```bash mu --help ``` Every verb's `--help` is exhaustive (flags, defaults, interactions). Every successful invocation also prints a dim `Next:` block of suggested follow-up commands at the bottom — you never have to leave the terminal to learn what to do next. Every verb accepts `--json` for machine-readable output. Errors in `--json` mode emit a `{ error, message, nextSteps, exitCode }` record to stderr; the `nextSteps` array carries resolutions you can `eval` directly. (One verb opts out: `mu agent attach`, which prints a `tmux attach` command for a human to copy.) ### CLI conventions: validation errors Every operator-error path — missing required option, unknown option, unknown subcommand, missing positional, type-coercion failure, mutex flags, range checks — produces a uniform surface: - **Human path**: red `error: ` on stderr, then the failing subcommand's `--help` block (same text as `mu --help`), then exit **2**. - **`--json` path**: a structured envelope on stderr: ```json { "error": "UsageError", "message": "--self and --for are mutually exclusive", "nextSteps": [], "exitCode": 2, "usage": { "command": "mu task claim", "synopsis": "mu task claim [options] ", "description": "...", "args": [{"name": "id", "required": true, "variadic": false, "description": ""}], "options": [{"flags": "--self", "description": "...", "mandatory": false, "valueRequired": false}, ...] } } ``` `usage.options[].mandatory` is `true` when the operator MUST pass the option (`.requiredOption()` in commander terms). `valueRequired` is `true` when the option's argument can't be omitted if the flag IS passed (`` form vs bare flag). The two are independent. Exit 2 is the consistent code for the whole operator-error class — commander mistakes and handler-thrown `UsageError`s alike. Other classes keep their own codes (3 = not found, 4 = conflict, 5 = substrate, 6 = reaper, 7 = stall). ### CLI conventions: `--json` collection envelope Collection-read verbs emit a canonical `{items: T[], count: number}` shape on stdout: ```bash $ mu task list -w foo --json {"items":[{"name":"a",...},{"name":"b",...}],"count":2} ``` `count` is `items.length` pre-computed so `jq '.count'` is one less hop than `jq '.items | length'`. `mu workspace commits --json` adds `vcs`, `baseRef`, and `workspacePath` siblings. Applies to: `mu task list / next / owned-by / notes`, `mu workstream list`, `mu workstream destroy --empty` (dry-run), `mu archive list / search`, `mu workspace list / orphans / commits`, `mu undo` (group list), `mu log -n N` (read). Two carve-outs: - **`mu sql --json`** keeps bare-array rows. The verb is the typed- escape hatch; row shape is per-query, not part of the typed contract. - **`mu log --tail --json`** emits NDJSON (one JSON object per line) because it's a stream, not a collection. Stream consumers want one envelope per row, not a single envelope that grows forever. Singleton verbs (`mu task show`, `mu agent show`, `mu workstream init`, `mu task close`, ...) use object envelopes with named top-level fields (`{task, blockers, dependents, notes}`, `{taskName, ..., nextSteps}`). `items + count` is for collection reads only. ### CLI conventions: multi-value flags Multi-value flags accept repeated invocations (`--blocked-by a --blocked-by b`), a comma-separated value (`--blocked-by a,b`), or any mix. The signal is `` in the help-text metavar. Variadic positionals (`mu task wait a b c`) stay space-separated — operands are not commas, and single-valued flags (`-w`, `--title`) stay single. - `--by` on `mu task block` / `mu task unblock` is multi-value: `mu task block c --by a,b` adds both edges in one call. - `--status` on `mu task list` / `mu task next` is multi-value and returns the union. Omitting it applies no filter. - `mu task wait --status` stays single — "wait until reaches THIS status". **Empty vs blank fragments.** An *empty* fragment is dropped: a trailing or doubled comma is a typing artifact, so `--status "OPEN,"` means `[OPEN]`, and `mu task reparent --blocked-by ''` is the documented "clear every blocker" sentinel. A *blank* fragment — one that is entirely whitespace, like `--status " "` or the tail of `--status "OPEN, "` — is a usage error (exit 2) naming the flag. Nobody means "filter by the space character", and dropping it silently would return a different answer than the one typed. Same rule for `-w`, `--by`, and `--blocked-by`; see docs/VOCABULARY.md § Empty vs blank flag fragments. ### CLI conventions: flag vs positional The rule the CLI follows: > **The primary entity a verb acts on is POSITIONAL. Everything > else — scoping, modifiers, payload — is a flag.** So `mu task close `, `mu agent send `, `mu archive list