Missions + phases
A mission is a named objective: a directory under ~/.darkmux/missions/<mission-id>/ holding mission.json (description, a list of phase_ids, and a status: active/finalized/paused) plus the mission's own phases/ subdirectory. A phase is a time-boxed work unit inside a mission: its own JSON file at ~/.darkmux/missions/<mission-id>/phases/<phase-id>.json with status (planned/running/complete/abandoned), depends_on, and timestamps. Everything for one mission lives under that one directory. Nothing is split across separate top-level missions/ and phases/ trees.
Note for operators with existing state: earlier versions of darkmux nested everything under ~/.darkmux/crew/ (roles/, missions/, phases/). The loader transparently falls back to that layout. Separately, a mission whose phase JSONs still live under a legacy sprints/ subdirectory (pre-rename) instead of phases/ also reads and writes there transparently. Run darkmux doctor for a copy-pasteable mv script to flatten onto the current layout when you're ready. One older layout is not transparent: the original flat ~/.darkmux/missions/<id>.json + ~/.darkmux/phases/<id>.json shape (pre-mission-scoped-directories) needs an explicit one-time darkmux mission migrate to move into the nested layout above before it'll load. That same verb also synthesizes a config-snapshot.json for any nested-layout mission that predates mission launch and doesn't have one yet: a trivial, task-less config built from the mission's own JSON, so an old hand-authored instance reads honestly as the freeform/manual mission it always was. darkmux mission migrate (dry run) then --apply covers both.
Authoring a mission
A mission starts from a mission config: the built-in ones (darkmux mission config list shows them, darkmux mission config show <id> renders one's graph and the model each role resolves to), or one you write at ~/.darkmux/mission-configs/<id>.json. Then darkmux mission launch <id> mints a running mission instance from it and drives it as a task graph, gated on your sign-off.
Turning unstructured intent (a pasted issue, a page, some notes) into a config is your frontier orchestrator's job, not darkmux's: hand it the text and the config schema below, and review what it writes before launching. (The mission propose verb that used to dispatch a local utility model for this was removed in 4.0, #2912: it emitted the pre-graph mission shape, which nothing could launch.)
Authoring a mission config by hand
You write the config JSON directly at ~/.darkmux/mission-configs/<id>.json, then run darkmux mission launch <id>. This is how every custom mission is authored; your orchestrator can write the file for you from a plain-language description of the work. See config authoring below for the shape.
Hand-authoring the running instance JSON directly (writing mission.json/phases/<id>.json yourself under ~/.darkmux/missions/) is not a documented path any more. Those files still exist on disk exactly as before, and they're still plain, human-readable JSON you can open and inspect; but they're now system-managed state that mission launch writes for you, the same way a database's on-disk pages are real files you could technically hand-edit but aren't meant to. Write a config; launch it.
When to use missions vs. not
Mission/phase is overhead. It pays back only when you'd benefit from durable state for the work. Three patterns to pick from:
| Pattern | Shape | When |
|---|
| Skip |
No mission. Just darkmux dispatch coder "..." ad-hoc. |
Single-shot work, no follow-up expected. The dispatch record itself is the only artifact you need. |
| Duration container |
One mission with phase_ids: []. Start it; close it; that's it. |
You want start/close timestamps for an engagement-level chunk of work, but the work isn't decomposable into named sub-steps. |
| Decomposed plan |
Mission + N phases. Pre-plan or grow via mission add-phase. |
Multi-step work where the wall-clock arcs per phase matter, dependencies between phases matter, or you want the viewer's timeline as an explicit feedback surface. |
The practical heuristic: if you can't articulate what the viewer would show you at the end of the mission, you probably don't need a mission. If the answer is "a 3-arc timeline with these durations and these dispatch records", missions earn their keep.
Mission config shape
A mission config is the DATA a mission is launched FROM. It declares the phases the launched instance will have, plus (optionally) the runtime-only inputs the launcher needs supplied at launch time (a worktree path, a case id, resolved crew staffing) that don't belong baked into a reusable document. Save it at ~/.darkmux/mission-configs/<id>.json:
{
"id": "draft-blog-post",
"name": "Draft Blog Post",
"description": "Draft a blog post on local-AI bounded-task patterns.",
"schema_version": "1.1",
"phases": [
{
"id": "s1-outline",
"description": "Write a one-page outline: thesis, three supporting sections, closing reframe."
},
{
"id": "s2-draft",
"description": "Flesh out the outline into a full first draft."
}
]
}
A phase with no tasks array (as both phases above) is a valid, common shape: a freeform/manual phase whose work happens by hand, or via ad-hoc darkmux dispatch calls, rather than an automated Task/Step graph. Phase order is the list position; there's no separate dependency field to set.
Launching a config: mission launch
darkmux mission launch draft-blog-post
This resolves the config (user tier first, then any on-disk template, then an embedded built-in), validates it, and mints a running mission INSTANCE: mission.json, one phases/<id>.json per declared phase, and a config-snapshot.json, a frozen copy of the resolved config alongside the instance, so a later edit to the source config never orphans an already-running instance's own record of what it ran. For a config whose phases have no tasks (as above), launch mints the instance and starts the mission, then leaves the work to you: do each phase by hand (or via ad-hoc darkmux dispatch calls), and when the whole mission is done, close it out with darkmux mission finalize draft-blog-post (or darkmux mission abort draft-blog-post to kill it). The mission graph derives phase status; the whole-mission terminals reconcile the phases for you.
Every launch mints a fresh, unique instance id (<config-id>-<unix-secs>-<6-hex-token>), whether or not you pass --input/--param values (#1503: two launches of the same config are two different pieces of AI work, never collapsed onto one id). The launch output prints the exact id; use it verbatim for the follow-up commands. Launches of the same config sharing the same inputs are grouped for later comparison via a separate spec fingerprint recorded on the instance (a hash of the collected inputs), useful for corpus analysis, but that fingerprint is never the instance id itself.
A config can declare runtime-only inputs it needs from its launcher (see the built-in coder-phase config for a worked example: it needs a worktree path, a branch, and a base ref). Supply them with a JSON file or individual overrides:
darkmux mission launch coder-phase \
--input inputs.json \
--param role=coder \
--param branch=my-feature
--param always wins over the same key in --input's file. Launching a config with a missing required input bails loud, listing exactly what's missing plus a copy-pasteable example of both forms. Launching the SAME config with the SAME inputs twice is not idempotent: each call mints a distinct fresh instance (#1503 removed the old reuse/reopen-by-derived-id path entirely: there's no terminal instance to silently reopen, and no way for a relaunch to collide with a prior run's id).
Exit codes: 0 for a freeform mint, or a coder-phase run whose QA came back clean or flags-only (the run stops at the sign-off gate with the phase still Running); 1 for a coder dispatch error; 2 when QA found blockers to resolve before shipping; 3 when QA could not run and manual review is required; 4 when the instance was minted but the graph uses step kinds this launcher cannot execute yet.
Inspecting the config registry: mission config list / show
Before launching, see what's registered and what it would actually do (#1860). darkmux mission config list enumerates every config id across the same user → on-disk → embedded tiers mission launch searches, one row each with its name, winning tier, phase/task counts, and whether it advertises a panel command. A config that fails to load still prints as a row naming the error — one broken user-tier override never hides the rest of the registry.
darkmux mission config list
darkmux mission config show <id> prints the whole graph — every phase, task, and step, the step kind each step names and whether THIS binary can construct it (the identical check mission launch exits 4 against, surfaced before launch instead of at it) — and, for every task with a role_id, the profile and model that role resolves to right now: a launch override, the role_profiles map, or the default_profile fallback (the operator never has to wonder where the decision came from), plus whether that model is currently loaded. Pass --param <role>=<profile> (repeatable) to preview a planned override exactly as mission launch <id> --param <role>=<profile> would apply it — on the review route: review and any variant whose graph uses the review step kinds. On any other config (e.g. coder-phase), mission launch ignores --param <role>=<profile> entirely (a coder-phase --param role=<id> is a DIFFERENT knob — it rebinds the task's own role_id, not a role→profile binding), and show mirrors that: the override is neutered and a warning names why, rather than claiming a parity that doesn't hold.
darkmux mission config show review
darkmux mission config show review --param reviewer=review-mid
Both verbs are strictly READ-ONLY and take --json for machine consumption. Neither resolves any NEW data or logic beyond what mission launch/dispatch already resolve silently at run time — this is that same resolution, surfaced ahead of time. A missing profiles registry or an unreachable LMStudio never fails the command: the affected fields report "unavailable" inline instead.
Mission JSON shape
Generated by mission launch at ~/.darkmux/missions/deploy-rewrite/mission.json. This is system-managed state now (see the note above): still plain JSON you can open and read, just not a file you're expected to hand-author:
{
"id": "deploy-rewrite",
"description": "Rewrite the deploy pipeline to use the new artifact store",
"status": "active",
"phase_ids": ["deploy-rewrite-s1-baseline", "deploy-rewrite-s2-cutover"],
"created_ts": 1778685866
}
Phase JSON shape
Also generated by mission launch, at ~/.darkmux/missions/deploy-rewrite/phases/deploy-rewrite-s1-baseline.json. The file's own basename is the phase id; mission_id inside it is redundant with the parent directory but kept for self-description (a phase JSON is meaningful even copied out on its own):
{
"id": "deploy-rewrite-s1-baseline",
"mission_id": "deploy-rewrite",
"description": "Capture a baseline of current deploy timing + artifact sizes",
"status": "planned",
"depends_on": [],
"created_ts": 1778685866
}
Worked example: a minimum-viable mission
The smallest useful shape: one config, one phase. Just enough to see the lifecycle move and the cyan records land in the viewer.
Any phase, task or step may carry "enabled": false. It is pruned when the run is minted, so the run shows exactly what will execute and nothing gray; the run's config-snapshot.json and graph-report.json record what was left out and why, and mission status prints the count. There is no CLI override: edit the config and launch.
A task may instead declare grow, making it a template that a phase boundary expands. The launcher reads the from task's last step output as a path to a JSON file, takes the array at items, and mints one copy per item, substituting {{item.field}} into the id and every step's config. Zero items grows nothing and the phase still completes.
"grow": { "from": "plan-task", "items": "units", "id": "{{item.id}}",
"config": { "unit": "{{item.id}}", "rule": "{{item.rule}}" } }
1. Make sure the directory exists
mkdir -p ~/.darkmux/mission-configs
2. Save the mission config
Save the following at ~/.darkmux/mission-configs/draft-blog-post.json:
{
"id": "draft-blog-post",
"name": "Draft Blog Post",
"description": "Draft a blog post on local-AI bounded-task patterns.",
"phases": [
{
"id": "s1-outline",
"description": "Write a one-page outline: thesis, three supporting sections, closing reframe."
}
]
}
3. Launch it
darkmux mission launch draft-blog-post
4. Do the work, then finalize
darkmux mission finalize draft-blog-post
Every transition emits a flow record. Open darkmux.com/flow/, click Connect, and you'll see the cyan operator-tier records as the lifecycle moves.
Mission without phases (duration container)
You can omit phases entirely. A config with phases: [] is valid: launching it is just a start/close timestamp container for an engagement-level chunk of work that isn't decomposable.
{
"id": "japan-trip-2026-05",
"name": "Japan Trip 2026-05",
"description": "10-day Japan trip, May 20-30."
}
Then darkmux mission launch japan-trip-2026-05 once, when the trip begins, and darkmux mission finalize japan-trip-2026-05 when it ends. The viewer will show the wall-clock duration.
You can also mission add-phase later if structure emerges mid-trip. The empty-phase mission grows into a decomposed one as needed.
Growing the plan: the multi-phase shape
For mission-shaped work with clear decomposition (a campaign, a deploy, a multi-week research arc), the natural pattern is one config with one phase entry per planned step. Same shape as the minimum-viable example, just more phases in the array.
For example, a marketing-campaign config might declare three phases: positioning research, messaging draft, launch checklist. Display order in the viewer follows the config's phase array order, which becomes the launched mission's phase_ids array order; there's no separate dependency field to set at the phase level.
Mission/phase is a generic plan abstraction.
The examples here aren't all software engineering: blog drafts, marketing campaigns, travel planning all fit. Anywhere you want explicit state for "this is what I'm working toward" and "this is the named piece I'm currently on," mission + phase is the shape. The schema doesn't care what the work is.
Drive the lifecycle
darkmux mission launch <config>
darkmux mission pause <id>
darkmux mission resume <id>
darkmux mission finalize <id>
darkmux mission abort <id>
There's no manual per-phase lifecycle any more: the mission graph derives each phase's status, and the whole-mission terminals (finalize/abort) reconcile the phases for you. Every transition emits a flow record. Open the viewer in a new tab as you run these. The phase-progress widget in the header shows N/M done across active missions, and the record stream below shows the cyan operator-tier transitions in order.
