Parallelize your AI coding agents. Ship faster.
Important
Migrated fork — OpenCode V2. This version has been ported to the OpenCode V2 plugin API (@opencode/plugin 2.x) and is not compatible with OpenCode V1. The migration is functional but partial: see Migration status for what is validated, what is not, and what is not migrated yet.
Migration status • Quick Start • Examples • Launch vs Plan • How It Works • Tools Reference • Orchestrated Plans • Configuration • FAQ
AI coding is fast, but context switching is slow. Running multiple agents in a single directory leads to file conflicts, messy git history, and "who-changed-what" headaches. You end up waiting for one agent to finish before starting the next, wasting the most valuable resource you have: your time (and, occasionally, your patience).
Mission Control orchestrates isolated environments for your AI agents. In this migrated version, each job gets its own git worktree, a local opencode serve process, and a tmux session — complete filesystem isolation. You can monitor progress, capture output, or attach to any session at any time. When the work is done, sync changes back or create a PR with a single command.
For complex multi-task workflows, the Plan System handles dependency graphs, merge ordering, automated testing, and PR creation — all orchestrated automatically. Less herding cats, more shipping code.
┌─────────────────────────┐
│ Your Main Session │
│ (Command Center) │
└────────────┬────────────┘
│
mc_launch / mc_plan
│
┌───────────────────┼───────────────────┐
│ │ │
┌──────┴──────┐ ┌──────┴──────┐ ┌──────┴──────┐
│ Job A │ │ Job B │ │ Job C │
│ Worktree │ │ Worktree │ │ Worktree │
│ tmux+serve │ │ tmux+serve │ │ tmux+serve │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
└───────────────────┼───────────────────┘
│
mc_diff / mc_pr
mc_merge / mc_sync
│
▼
┌─────────────────┐
│ Main Branch │
└─────────────────┘
- Launch —
mc_launchcreates a git worktree and starts a localopencode serveinside a tmux session, then prompts the agent - Monitor — The monitor subscribes to each serve job's SSE stream; TUI jobs are polled for pane state and exit status
- Observe — Use
mc_status,mc_capture, ormc_attachto check on progress - Integrate — Use
mc_diffto review,mc_prto create a PR,mc_mergeto merge, ormc_syncto rebase
This repository is a migration of Mission Control to OpenCode V2. It targets
@opencode/plugin / @opencode/client 2.x and has been validated with OpenCode
2.2.5 on Linux/WSL2. It does not work with OpenCode V1.
The port is functional, but not every V1 feature could be carried over as-is and not every path has been validated end-to-end yet.
| V1 behavior | V2 reality | What this version does |
|---|---|---|
| Server-side toast notifications | No server-side toast API | Toasts are emitted over the plugin RPC channel and rendered by a companion TUI plugin (src/tui.ts) |
| Question tool with prompt/answer | V2 uses first-class forms | mc_answer relays answers through session.form.list / session.form.reply |
noReply on a prompt |
Removed | Uses session.synthetic({ resume: false }); the message stays in the pending inbox until the next turn |
session.idle as the completion signal |
Serve-mode runs emit session.execution.succeeded / .failed / .interrupted |
The monitor uses execution events for serve jobs; TUI jobs poll the pane and trust an exit code of 0 or an explicit mc_report |
opencode -m <model> in the TUI |
-m/--model only exists on opencode run |
Vanilla plan jobs run through opencode run -m; OMO modes keep the TUI and its default model |
| Unauthenticated local server | opencode serve always requires auth |
Each job gets a random password and uses Basic auth (opencode:<password>) |
| Tool context exposes the directory/worktree | V2 Tool.Context has no directory |
The plugin location is bound into mc_report at registration; cwd is threaded through job state and reports |
Permission action bash |
Permission action is shell |
Permission relay and auto-approval use the V2 action names |
| V1 hooks/plugin shape | V2 plugin API | Plugin.define, ctx.tool.transform, ctx.event.subscribe, ctx.rpc.register |
- Plugin loading, tool and command registration
- Direct slash commands
- Serve-mode job launch: worktree, per-job
opencode serve, per-job password, tmux session - Job completion through
session.execution.succeeded mc_reportwriting to the correct project data directory (shared-server case)mc_diff,mc_status,mc_capture,mc_cleanup,mc_kill- Multiple locations / plugin instances
- V2 question forms +
mc_answer session.synthetic({ resume: false })(V1noReplyequivalent)- Permission auto-approval
- Plan flow:
mc_plan(copilot) →mc_plan_approve→opencode runjob → commit → report → squash merge into the integration branch →mc_plan_cancelcleanup - Supervisor checkpoints
pre_mergeandpre_pr(including persisted approvals across processes) - Multi-job plans: parallel launch,
dependsOnordering, real merge conflict +on_errorretry,touchSetviolation +relaunch - Real TUI toast rendering (auto-status toast observed in a live TUI session)
- Real PR creation is not validated.
ghand a git remote were not available in the test environment. Execution reachesgit push originand stops there; thegh pr createpath is covered by unit tests only. A failed PR stage currently does not persist its error reason on the plan. - Supervisor
retry/relaunchwas not live-tested. Retry and relaunch were validated on normal plans; the supervisor variants are covered by unit tests. - OMO modes (
plan,ralph,ulw) were not live-tested. They require Oh-My-OpenCode to be installed; the launcher path is preserved but unverified in a real session. - Large plans and saturation were not stress-tested. Live tests used at most three jobs;
maxParallel, merge-train contention, and many concurrent worktrees are not exercised. - Remote workflows are untested. Push, PR, branch protection, and CI integration are not validated.
- Windows native is not supported/tested. Only Linux and WSL2 were validated.
- V1 → V2 data migration is not guaranteed. Existing V1 jobs/sessions are not resumed; start from a clean Mission Control state.
- Toasts: the auto-status toast was validated visually; other toast types (checkpoints, errors) use the same channel but were not individually observed.
- Native V2 backend is not implemented (Phase 2). This version still uses tmux + one local
opencode serveper job. Native V2 worktrees/sessions are planned but not done. - Packaging/publishing is not done. There is no npm release, no
.d.ts, and the package has not been tested as an installed tarball. Repository metadata still points to the upstream project. - Compaction, model tracking, and notification edge cases are covered by unit tests only.
| Tool | Required | Purpose |
|---|---|---|
| OpenCode 2.x | Yes | Plugin host (validated with 2.2.5) |
| git | Yes | Worktrees |
| tmux | Yes, for the current backend | Hosts each job's local server |
| Bun (or npm) | For dependency install | bun install in the plugin directory |
| gh | Only for mc_pr |
PR creation (not validated here) |
sudo apt install tmux git
opencode --version # must be 2.xClone inside the WSL filesystem, not under /mnt/c:
git clone <your-fork-url> ~/opencode-mission-control
cd ~/opencode-mission-control
bun installNo build step is required: OpenCode loads the TypeScript sources directly.
In the project where you want to use Mission Control (opencode.jsonc or opencode.json):
{
"$schema": "https://opencode.ai/config.json",
"plugins": ["/home/<user>/opencode-mission-control"]
}The path must point to the plugin directory, not to a file.
Server plugins and TUI plugins are configured separately. Add Mission Control to the
global CLI config (~/.config/opencode/cli.json, or $XDG_CONFIG_HOME/opencode/cli.json)
using the singular plugin key:
{
"$schema": "https://opencode.ai/v2/cli.json",
"plugin": ["/home/<user>/opencode-mission-control"]
}Everything works without this entry; only in-TUI toasts require it.
Restart OpenCode, then run mc_status (or /mc-status). On the first mc_launch,
Mission Control creates a worktree, starts a local opencode serve on
127.0.0.1:14100-14199 inside a tmux session, and prompts the agent.
State is stored under:
~/.local/share/opencode-mission-control/<project>/
├── state/jobs.json
├── state/plan.json
└── reports/
mc_launch
└─ git worktree
└─ tmux session
└─ opencode serve (127.0.0.1, random port + password)
└─ OpenCode session + agent
- The monitor subscribes to each serve job's SSE stream and reacts to
session.execution.succeeded/.failed/.interrupted. - Plan jobs run in their worktree through
opencode run -m <model>. - Toasts go from the server plugin to the TUI companion plugin over the RPC channel.
Phase 2 (not implemented) would replace tmux + per-job opencode serve with native
V2 worktrees and sessions on the shared server.
| Tool | Required | Purpose |
|---|---|---|
| OpenCode 2.x | Yes | Plugin host (validated with 2.2.5) |
| tmux | Yes, for the current backend | Hosts each job's local server |
| git | Yes | Worktree management |
| Bun or npm | For installation | Install the plugin's dependencies |
| gh | For mc_pr |
GitHub PR creation (not validated here) |
Requires OpenCode V2 (plugin API
@opencode/plugin2.x). This version is a partial migration: see Migration status.
Most OpenCode setups install plugins listed in opencode.json automatically, so you usually do not run npm install manually.
Add this plugin entry:
{
"plugins": [
"opencode-mission-control"
]
}If you are developing this repository itself, use the local dev flow in Development.
Mission Control's toast notifications are rendered by a companion TUI plugin, which OpenCode V2 configures separately
from server plugins. Add Mission Control to the global CLI config (~/.config/opencode/cli.json, or
$XDG_CONFIG_HOME/opencode/cli.json) using the plugin array:
{
"$schema": "https://opencode.ai/v2/cli.json",
"plugin": ["opencode-mission-control"]
}Everything else works without this entry; only the in-TUI toasts require it.
You: "Fix the login bug and add the pricing table — do both at once."
AI: Launching two parallel jobs now.
→ mc_launch(name: "fix-login", prompt: "Fix the authentication bug in...")
→ mc_launch(name: "add-pricing", prompt: "Create a pricing table component...")
You: "How's the login fix going?"
AI: → mc_capture(name: "fix-login")
Still running. Here's the latest output from that session...
You: "Login fix looks good. Create a PR."
AI: → mc_pr(name: "fix-login", title: "Fix: auth token validation")
PR created: https://github.com/you/repo/pull/42
You: "Run a docs cleanup and a bugfix in parallel."
AI: → mc_launch(name: "docs-cleanup", prompt: "Clean up README wording")
→ mc_launch(name: "fix-auth-timeout", prompt: "Fix token timeout bug")
You: "Show me what changed in the bugfix branch."
AI: → mc_diff(name: "fix-auth-timeout")
You: "What's happening right now?"
AI: → mc_overview()
You: "Kill the experiment and remove its worktree."
AI: → mc_kill(name: "wild-experiment")
→ mc_cleanup(name: "wild-experiment", deleteBranch: true)
You: "Rebase the feature job onto latest main."
AI: → mc_sync(name: "feature-checkout", strategy: "rebase")
AI: → mc_plan(
name: "feat: search upgrade",
mode: "autopilot",
jobs: [
{ name: "schema", prompt: "Add search index tables" },
{ name: "api", prompt: "Implement search endpoints", dependsOn: ["schema"] },
{ name: "ui", prompt: "Build search UI", dependsOn: ["api"] }
]
)
Because waiting is overrated.
You: "Fix these bugs on the develop branch, not main."
AI: → mc_launch(name: "fix-auth", prompt: "Fix the JWT bug", baseBranch: "develop")
→ mc_launch(name: "fix-timeout", prompt: "Fix the timeout issue", baseBranch: "develop")
You: "Auth fix looks good. Create a PR targeting develop."
AI: → mc_pr(name: "fix-auth", title: "fix: JWT token validation")
PR created targeting 'develop': https://github.com/you/repo/pull/43
AI: → mc_plan(
name: "feat: search upgrade",
baseBranch: "develop",
mode: "autopilot",
jobs: [
{ name: "schema", prompt: "Add search tables" },
{ name: "api", prompt: "Build search API", dependsOn: ["schema"] }
]
)
Result:
• Integration branch created from 'develop'
• schema launches from 'develop', api launches from integration HEAD
• PR targets 'develop' when all jobs merge
You: "The develop branch has new changes. Update my job."
AI: → mc_sync(name: "fix-auth", source: "origin")
Successfully synced job "fix-auth" using rebase strategy.
By default, mc_sync syncs against the local base branch. Use source: "origin" to fetch the latest from the remote first.
The two main entry points — mc_launch and mc_plan — serve different workflows. Picking the right one saves you time and merge headaches.
| Scenario | Why Launch |
|---|---|
| Independent tasks on different files | No dependency management needed. Launch both, merge in any order. |
| Quick experiments or spikes | Spin up a job, review the diff, keep it or kill it. Zero ceremony. |
| You want full manual control | You decide what merges, when, and in what order. |
| More than 3 concurrent jobs | Plans respect maxParallel (default 3). Standalone launches have no limit. |
Typical launch workflow:
mc_launch("fix-auth", "Fix the JWT expiry bug in src/auth/")
mc_launch("add-pricing", "Build pricing table in src/components/pricing/")
↓ both complete
mc_diff("fix-auth") → review
mc_merge("fix-auth") → into main
mc_diff("add-pricing") → review
mc_merge("add-pricing") → into main
| Scenario | Why Plan |
|---|---|
| Work has a dependency chain | Job B needs job A to finish first. dependsOn handles ordering and code propagation automatically. |
| You want automated test gating | The merge train runs your test suite after each merge and rolls back on failure. You don't get this with standalone launches. |
| You want a single PR for a feature | Plan creates one integration branch and opens a single PR when everything merges. |
| You want hands-off execution | Autopilot mode: launch, merge, test, PR — all automatic. Walk away. |
Typical plan workflow:
mc_plan("feat: search upgrade", mode: "autopilot", jobs: [
{ name: "schema", prompt: "Add search tables..." },
{ name: "api", prompt: "Build search endpoints...", dependsOn: ["schema"] },
{ name: "ui", prompt: "Build search UI...", dependsOn: ["api"] }
])
↓ automatic
schema launches → completes → merges into integration branch
api launches (sees schema's changes) → completes → merges → tests run
ui launches (sees schema + api changes) → completes → merges → tests run
↓
PR created automatically
Do the jobs touch completely different files?
YES → mc_launch both in parallel, merge independently.
Does job B need code that job A creates?
YES → mc_plan with dependsOn. B launches from the integration
branch and sees A's changes.
Do you want tests to run after each merge?
YES → mc_plan (merge train runs testCommand automatically).
Do you want one PR for all the work?
YES → mc_plan.
None of the above?
→ mc_launch. Simpler, more flexible, less overhead.
The trickiest scenario is when multiple jobs need to edit the same files — for example, two features on the same React view. Even if the work is conceptually separate ("left panel" vs "right panel"), git sees two branches editing the same lines of the same file.
The scaffold pattern solves this by creating file boundaries first:
Step 1: Launch a quick scaffolding job
mc_launch("scaffold", "Split Dashboard.tsx into separate
LeftPanel and RightPanel component files. Keep them as
stubs with TODO comments. Update Dashboard.tsx to import
and render both.")
Step 2: Merge the scaffold
mc_merge("scaffold")
Step 3: Launch the real work in parallel — now they touch different files
mc_launch("left-panel", "Implement LeftPanel in src/components/LeftPanel.tsx...")
mc_launch("right-panel", "Implement RightPanel in src/components/RightPanel.tsx...")
Step 4: Merge both — no conflicts
mc_merge("left-panel")
mc_merge("right-panel")
The scaffold job takes a couple of minutes and eliminates the merge conflict surface entirely.
If you can't separate the files (heavy shared state, tightly coupled components), don't force parallelism. Use a plan with dependsOn so the second job builds on top of the first, or just run them sequentially with standalone launches.
| Overlap Level | Strategy |
|---|---|
| No shared files | Parallel mc_launch |
| 1-2 shared files (parent component, types) | Scaffold first, then parallel |
| Many shared files (shared state, hooks, styles) | Sequential — mc_plan with dependsOn or manual launches |
Launch a new parallel AI coding session in an isolated worktree.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string |
Yes | — | Job name (used for branch name and tmux/SSE identity) |
prompt |
string |
Yes | — | Task prompt for the spawned AI agent |
branch |
string |
No | mc/{name} |
Git branch name |
baseBranch |
string |
No | Default branch | Branch or ref to start from (e.g. "develop") |
placement |
"session" | "window" |
No | Config default | session creates a new tmux session; window adds a window to the current session (current backend) |
mode |
"vanilla" | "plan" | "ralph" | "ulw" |
No | Config default | Execution mode (see OMO Integration) |
planFile |
string |
No | — | Plan file path (for plan mode) |
copyFiles |
string[] |
No | — | Files to copy from main worktree (e.g. [".env", ".env.local"]) |
symlinkDirs |
string[] |
No | — | Directories to symlink (e.g. ["node_modules"]). .opencode is always included. |
commands |
string[] |
No | — | Shell commands to run after worktree creation (e.g. ["bun install"]). Validated against injection patterns — use allowUnsafeCommands in config to bypass. |
What happens on launch:
- Creates a new git worktree on a dedicated branch
- Runs post-create hooks (copy files, create symlinks, run commands)
- Spins up a tmux session or window (current backend)
- Starts a local
opencode serveon a random port with a per-job password - Creates an OpenCode session in the worktree and sends the prompt
- Sets up the pane-died hook and SSE monitoring for the job
List all jobs with their current status.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
status |
"all" | "running" | "completed" | "failed" |
No | "all" |
Filter by status |
Get detailed status of a specific job including branch, worktree path, tmux target, duration, and mode.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string |
Yes | Job name |
Capture the last N lines of terminal output from a job's tmux pane (current backend).
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string |
Yes | — | Job name |
lines |
number |
No | 100 |
Number of lines to capture |
Get the tmux command to attach to a job's terminal session (current backend).
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string |
Yes | Job name |
Stop a running job by terminating its tmux session/window (current backend).
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string |
Yes | — | Job name |
force |
boolean |
No | false |
Force kill |
Remove finished job worktrees and metadata.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string |
No | — | Specific job to clean up |
all |
boolean |
No | false |
Clean up all non-running jobs |
deleteBranch |
boolean |
No | false |
Also delete the git branch |
Get a complete dashboard overview of all Mission Control activity — running jobs, recent completions, failures, active plans, alerts, and suggested next actions. This is the best starting point when checking in on your jobs.
No parameters.
Report agent status back to Mission Control. Auto-detects which job is calling based on the current worktree. This tool is designed to be called by spawned agents from within their managed worktrees — it cannot be used from the main session.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
status |
"working" | "blocked" | "needs_review" | "completed" | "progress" |
Yes | — | Current agent status |
message |
string |
Yes | — | Human-readable status message |
progress |
number |
No | — | Completion percentage (0–100) |
Reports are used by the monitoring system to:
- Trigger notifications (e.g., when an agent reports
blockedorneeds_review) - Signal explicit completion (a
completedreport immediately marks the job as done) - Provide progress visibility via
mc_statusandmc_overview
Compare a job's branch against the base branch.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string |
Yes | — | Job name |
stat |
boolean |
No | false |
Show diffstat summary only |
baseBranch |
string |
No | Job's base branch | Override base branch for diff comparison |
Push the job's branch and create a GitHub Pull Request. Requires the gh CLI to be authenticated.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string |
Yes | — | Job name |
title |
string |
No | Job name | PR title — use Conventional Commits format (e.g. feat: add login, fix: resolve timeout) |
body |
string |
No | PR template or auto-generated | PR body. If omitted, uses .github/pull_request_template.md if found, otherwise generates a summary. |
baseBranch |
string |
No | Job's base branch or default | Target branch for the PR (falls back to job's baseBranch, then default branch) |
draft |
boolean |
No | false |
Create as draft PR |
Pull the latest changes from the base branch into a job's worktree.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string |
Yes | — | Job name |
strategy |
"rebase" | "merge" |
No | "rebase" |
Sync strategy. Aborts on conflict and reports affected files. |
source |
"local" | "origin" |
No | "local" |
Sync against the local base branch (default) or fetch from origin first |
Merge a job's branch back into the main worktree.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string |
Yes | — | Job name |
strategy |
"squash" | "ff-only" | "merge" |
No | Config mergeStrategy (default "squash") |
Merge strategy. squash squashes all commits; ff-only rebases then fast-forwards; merge creates a merge commit (--no-ff). |
squash |
boolean |
No | false |
Deprecated — use strategy instead. If set and no strategy is provided, squash: true maps to strategy: "squash". |
message |
string |
No | Auto-generated | Merge commit message |
For workflows with dependencies between jobs, the Plan System manages the full lifecycle — from parallel execution to merge ordering to PR creation.
Create and start a multi-job orchestrated plan.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string |
Yes | — | Plan name — used as the PR title, so use Conventional Commits format (e.g. feat: add search, fix: resolve auth bugs) |
jobs |
JobSpec[] |
Yes | — | Array of job definitions (see below) |
mode |
"autopilot" | "copilot" | "supervisor" |
No | "autopilot" |
Execution mode |
placement |
"session" | "window" |
No | Config default | tmux placement for all jobs in this plan |
baseBranch |
string |
No | Default branch | Base branch for the integration branch and PR target |
JobSpec fields:
| Field | Type | Required | Description |
|---|---|---|---|
name |
string |
Yes | Unique job name |
prompt |
string |
Yes | Task prompt for the AI agent |
dependsOn |
string[] |
No | Job names this job depends on (must complete and merge first) |
touchSet |
string[] |
No | File globs this job expects to modify. After completion, the orchestrator validates that only files matching these patterns were changed. Violations pause the plan — see TouchSet Enforcement. |
mode |
"vanilla" | "plan" | "ralph" | "ulw" |
No | Execution mode override (defaults to omo.defaultMode config) |
copyFiles |
string[] |
No | Files to copy into the worktree |
symlinkDirs |
string[] |
No | Directories to symlink into the worktree |
commands |
string[] |
No | Post-creation shell commands |
| Mode | Behavior |
|---|---|
| Autopilot | Full hands-off execution. Jobs launch, merge, and a PR is created automatically. |
| Copilot | Plan is created in pending state. You review it with mc_plan_status, then approve with mc_plan_approve to start. |
| Supervisor | Execution pauses at checkpoints (pre_merge, on_error, pre_pr) requiring manual mc_plan_approve to continue. |
mc_plan
│
├─ Validate (unique names, valid deps, no circular deps)
├─ Create integration branch: mc/integration-{plan-id}
│
├─ [copilot] ──→ Pause (pending) ──→ mc_plan_approve ──→ Continue
│
├─ Topological sort jobs by dependencies
├─ Launch jobs (respects maxParallel limit)
│ • Root jobs branch from baseCommit
│ • Dependent jobs branch from integration HEAD (sees merged code)
│ • Branches use plan-scoped naming: mc/plan/{planId}/{jobName}
│
│ ┌──────── Reconciler Loop (5s) ────────┐
│ │ │
│ │ • Check dependency satisfaction │
│ │ • Launch ready jobs │
│ │ • Process merge train │
│ │ • [supervisor] Pause at checkpoints │
│ │ │
│ └───────────────────────────────────────┘
│
├─ Merge Train: merge each job into integration branch
│ ├─ Merge (--no-ff)
│ ├─ Run test command (if configured)
│ ├─ On failure → rollback merge, mark failed
│ └─ On conflict → abort, mark conflict
│
├─ All jobs merged → push integration branch
└─ Create PR via gh CLI
Show the current state of the active plan — job statuses, progress, and any checkpoints.
No parameters.
Approve a pending copilot plan, clear a supervisor checkpoint, or handle a failed job. When a touchSet violation pauses the plan, three actions are available:
| Parameter | Type | Required | Description |
|---|---|---|---|
checkpoint |
"pre_merge" | "on_error" | "pre_pr" |
No | Specific checkpoint to clear (supervisor mode) |
retry |
string |
No | Name of a failed/conflict/needs_rebase job to retry after manual fix. Re-validates touchSet before proceeding. |
relaunch |
string |
No | Name of a touchSet-failed job to relaunch. Spawns a new agent in the existing worktree with a correction prompt. |
TouchSet violation options:
| Action | Command | Behavior |
|---|---|---|
| Accept | mc_plan_approve(checkpoint: "on_error") |
Violations are legitimate — skip validation and proceed to merge |
| Relaunch | mc_plan_approve(checkpoint: "on_error", relaunch: "job") |
Spawn agent to fix — relaunches in existing worktree with violation details |
| Retry | mc_plan_approve(checkpoint: "on_error", retry: "job") |
You fixed it manually — re-validates touchSet, then proceeds if clean |
Cancel the active plan. Stops all running jobs, deletes the integration branch, and cleans up state.
No parameters.
This example uses mc_plan instead of four separate mc_launch calls because:
- The API needs the DB schema to exist —
api-endpointsimports from the schema tables thatdb-schemacreates. WithdependsOn, the API job launches from the integration branch and can see those tables. - The UI needs the API types —
dashboard-uiimports the response types thatapi-endpointsdefines. - Docs and UI are independent of each other — they both depend on
api-endpointsbut don't share files, so the plan runs them in parallel. - One PR for the whole feature — instead of four separate PRs, the merge train produces a single integration branch.
AI: I'll create a plan for the dashboard feature with proper dependencies.
→ mc_plan(
name: "feat: analytics dashboard",
mode: "autopilot",
jobs: [
{
name: "db-schema",
prompt: "Add the analytics tables to the database schema"
},
{
name: "api-endpoints",
prompt: "Create REST endpoints for the analytics dashboard",
dependsOn: ["db-schema"]
},
{
name: "dashboard-ui",
prompt: "Build the analytics dashboard React components",
dependsOn: ["api-endpoints"]
},
{
name: "docs",
prompt: "Update API documentation for analytics endpoints",
dependsOn: ["api-endpoints"]
}
]
)
Result:
• db-schema launches immediately
• api-endpoints waits for db-schema to merge — then launches with schema changes visible
• dashboard-ui and docs wait for api-endpoints — then run in parallel
• The merge train tests after each merge and rolls back on failure
• Once all merge successfully, a single PR is created automatically
Why not
mc_launch? You could launch these sequentially, merging each into main before starting the next. But you'd lose the automated test gating, the single integration PR, and the parallel execution ofdashboard-uianddocs. The plan handles the dependency graph, merge ordering, and PR creation — you just checkmc_plan_statusor wait for the completion notification.
When a job specifies touchSet patterns, the orchestrator validates the job's changes after completion — before the job enters the merge train. If the job modified files that don't match any touchSet glob, the plan pauses with an on_error checkpoint:
❌ Job "db-schema" modified files outside its touchSet:
Violations: src/types/search.ts, src/utils/format.ts
Allowed: src/db/**
Options:
Accept violations: mc_plan_approve(checkpoint: "on_error")
Agent fixes branch: mc_plan_approve(checkpoint: "on_error", relaunch: "db-schema")
You fix, re-check: mc_plan_approve(checkpoint: "on_error", retry: "db-schema")
| Option | When to use |
|---|---|
| Accept | You reviewed the violations and they're legitimate (e.g., the agent needed to update shared types) |
| Relaunch | The violations are accidental — a new agent spawns in the same worktree with a correction prompt to revert them |
| Retry | You manually fixed the branch — Mission Control re-validates the touchSet before proceeding |
The relaunch path reuses the existing worktree and branch. The correction agent sees the full git history and receives a prompt with the original task, the specific violations, and the allowed patterns. After the agent completes, touchSet validation runs again automatically.
The Merge Train is the engine behind plan integration. Each completed job's branch is merged into a dedicated integration branch (mc/integration-{plan-id}):
- TouchSet validation — If
touchSetis configured, verify the job only modified allowed files (violations pause the plan) - Merge —
git merge --no-ff {job-branch}into the integration worktree - Test — If a
testCommandis configured (or detected frompackage.json), it runs after each merge - Rollback — If tests fail or time out, the merge is automatically rolled back (
git merge --abortorgit reset --hard HEAD~1) - Conflict detection — Merge conflicts are caught, reported with file-level detail, and the merge is aborted
Once all jobs are merged and tests pass, the integration branch is pushed and a PR is created.
These commands run directly in the OpenCode chat — instant execution without an AI roundtrip (except /mc-launch, which delegates to the AI).
| Command | Description |
|---|---|
/mc |
Show Mission Control dashboard overview (runs mc_overview) |
/mc-jobs |
List all jobs and their status |
/mc-launch <prompt> |
Launch a new parallel agent (delegates to AI) |
/mc-status <name> |
Detailed status of a specific job |
/mc-attach <name> |
Get the tmux attach command |
/mc-capture <name> |
Capture terminal output from a job |
/mc-diff <name> |
Show changes in a job's branch |
/mc-plan |
Show plan status (runs mc_plan_status) |
/mc-approve |
Approve a pending plan or checkpoint |
/mc-cleanup [name] |
Clean up finished jobs (all if no name given) |
Mission Control runs an active background monitor — not a passive wrapper.
| Mechanism | Interval | What It Does |
|---|---|---|
| SSE subscription | Continuous | Serve jobs: subscribes to the job's opencode serve event stream and reacts to execution events |
| Polling | Every pollInterval (default 10s) |
TUI jobs: checks whether the tmux pane is still running |
| Pane death detection | Immediate | tmux pane-died hook fires when a pane closes, capturing exit status |
| Idle detection | idleThreshold (default 5min) |
Hashes terminal output; if unchanged for the threshold period and the session shows the idle prompt (ctrl+p commands), marks the job as completed |
| Exit code capture | On pane death | Exit code 0 → completed. Non-zero → failed. |
| Session state detection | On idle check | Distinguishes idle (waiting for input), streaming (AI is working), and unknown states |
| Hook | Trigger | Behavior |
|---|---|---|
session.execution.succeeded |
A job's agent turn completes | Marks the serve job completed and updates job state |
session.idle |
User's main session goes quiet | Shows toast notification with running job summary (rate-limited to once per 5 minutes) |
session.compacting |
OpenCode compacts context | Injects current job state into the AI's memory so it stays aware of background work |
pane-died |
tmux pane closes | Immediately captures exit status and updates job state |
Configuration is stored at ~/.local/share/opencode-mission-control/{project}/config.json.
{
"defaultPlacement": "session",
"pollInterval": 10000,
"idleThreshold": 300000,
"worktreeBasePath": "~/.local/share/opencode-mission-control",
"maxParallel": 3,
"autoCommit": true,
"mergeStrategy": "squash",
"testCommand": "bun test",
"testTimeout": 600000,
"worktreeSetup": {
"copyFiles": [".env", ".env.local"],
"symlinkDirs": ["node_modules"],
"commands": ["bun install"]
},
"omo": {
"enabled": true,
"defaultMode": "vanilla"
}
}| Field | Type | Default | Description |
|---|---|---|---|
defaultPlacement |
"session" | "window" |
"session" |
Default tmux placement for new jobs |
pollInterval |
number |
10000 |
Monitoring poll interval in ms (minimum 10s) |
idleThreshold |
number |
300000 |
Time in ms before an idle session is marked completed (default 5min) |
worktreeBasePath |
string |
~/.local/share/opencode-mission-control |
Root directory for worktrees |
maxParallel |
number |
3 |
Maximum concurrent jobs in an orchestrated plan |
autoCommit |
boolean |
true |
Whether to auto-commit changes in job worktrees before merging |
mergeStrategy |
"squash" | "ff-only" | "merge" |
"squash" |
Default merge strategy for mc_merge (can be overridden per-merge via the strategy param) |
testCommand |
string |
— | Command to run after each merge in the merge train (e.g. "bun test") |
testTimeout |
number |
600000 |
Timeout for test command in ms (default 10min) |
worktreeSetup.copyFiles |
string[] |
— | Files to copy into every new worktree (e.g. .env) |
worktreeSetup.symlinkDirs |
string[] |
— | Directories to symlink into every new worktree (e.g. node_modules) |
worktreeSetup.commands |
string[] |
— | Shell commands to run in every new worktree (e.g. bun install) |
omo.enabled |
boolean |
false |
Enable Oh-My-OpenCode integration |
omo.defaultMode |
string |
"vanilla" |
Default execution mode for spawned agents |
Every job creates a fresh git worktree. The worktreeSetup config (and per-job copyFiles/symlinkDirs/commands params) lets you prepare the environment:
copyFiles— Copies files from the main worktree (great for.env, config files)symlinkDirs— Creates symlinks to avoid re-downloading (great fornode_modules,.cache)commands— Runs shell commands after setup (great forbun install,pip install -e .). Commands are validated against shell injection patterns (;,&&,||,|, backticks,$()). SetallowUnsafeCommands: truein config to bypass validation for advanced use cases.
Per-job parameters are merged with the global worktreeSetup config.
If you use Oh-My-OpenCode (OMO), Mission Control unlocks advanced execution modes for spawned agents. These are optional — everything works without OMO installed.
| Mode | What It Does |
|---|---|
vanilla |
Standard opencode --prompt '...' execution |
plan |
Loads a Sisyphus plan. Copies .sisyphus/plans to the worktree and runs /start-work. |
ralph |
Starts a self-correcting Ralph Loop via /ralph-loop |
ulw |
Activates high-intensity Ultrawork mode via /ulw-loop |
OMO detection is automatic — Mission Control checks your opencode.json for the oh-my-opencode plugin.
Where are worktrees stored?
By default in ~/.local/share/opencode-mission-control/{project}/. They are real git worktrees — fully functional working copies.
Can I use this without tmux?
Not in this migrated version. tmux hosts the per-job local server and remains a hard requirement for the current backend. A native V2 backend (worktrees + sessions on the shared server) is planned for Phase 2.
Does it work with VS Code / Cursor?
Yes. You can open any job's worktree directory in your editor. The AI agents run in background tmux sessions independently.
What happens if my computer restarts?
Mission Control will detect dead tmux panes on the next poll and mark those jobs as failed. Use mc_cleanup to clean up.
How many jobs can I run at once?
As many as your machine can handle. Each job is a real OS process with its own file tree. The maxParallel setting only applies to orchestrated plans. Individual mc_launch calls have no built-in limit.
What if two jobs edit the same file?
Each job has its own worktree, so there are no runtime conflicts — they can't step on each other while running. Conflicts surface at merge time when you bring the branches back together (via mc_merge or the plan's merge train).
To avoid this, use the scaffold pattern: launch a quick job to split the shared file into separate components first, merge it, then launch the real work in parallel on the now-separate files. See Working With Shared Files for the full strategy.
Can I attach to a job's terminal while it's running?
Yes. Use mc_attach to get the tmux command, then run it in your terminal. You'll see the live AI session.
How does the plan merge train handle test failures?
If the configured testCommand fails after a merge, the merge is automatically rolled back. The job is marked as failed and the plan status updates accordingly (in supervisor mode, it pauses for your review).
What happens if a job modifies files outside its touchSet?
The plan pauses at an on_error checkpoint with three options: accept the violations if they're legitimate, relaunch the agent with a correction prompt to fix them, or retry after you fix the branch manually. See TouchSet Enforcement for details.
Why not just tell my agents to run git worktree add themselves?
You absolutely can — worktrees are just git. What you'd be rebuilding manually is everything around them:
- tmux session isolation with pane-death detection
- Background monitoring that tracks idle/streaming/completed states
- The merge train that tests after each integration and rolls back failures
- Dependency-aware scheduling with
maxParallellimits - The scaffold-and-sync workflow for shared files
- Automatic PR creation from integration branches
- The
mc_overviewdashboard that shows you what every agent is doing at a glance
Mission Control is the orchestration layer on top of worktrees, not the worktrees themselves.
Is this built by the OpenCode team?
No. This is an independent community plugin — not affiliated with or endorsed by the OpenCode team.
Do I need to manually install this with npm first?
Usually no. Put it in opencode.json and let OpenCode handle plugin installation. Manual npm install is mostly for local development or debugging.
This repo uses semantic versioning with semantic-release for automated npm releases.
How it works:
- Merge a Conventional Commit into
main(for example:feat:,fix:, orBREAKING CHANGE:). - GitHub Actions runs build + tests.
semantic-releasecalculates the next version, publishes to npm, creates a GitHub Release, and tags automatically.
Expected repository secrets:
NPM_TOKEN— npm publish token with package publish rights.GITHUB_TOKEN— provided automatically by GitHub Actions.
If your commit messages are vague, semantic-release gets moody.
bun install
bun run typecheck
bun run build
bun run testFound a bug? Have an idea? Check out CONTRIBUTING.md.
MIT
This plugin was heavily inspired by great work across the OpenCode ecosystem (any bugs are still 100% mine):
- slkiser/opencode-quota
- shekohex/opencode-pty
- Opencode-DCP/opencode-dynamic-context-pruning
- code-yeongyu/oh-my-opencode
- panta82/opencode-notificator
- 24601/opencode-zellij-namer
- kdcokenny/opencode-background-agents
- spoons-and-mirrors/subtask2
- mailshieldai/opencode-canvas
- joshuadavidthomas/opencode-handoff
