OpenCode Mission Control

Parallelize your AI coding agents. Ship faster.

Quick Start • Examples • How It Works • Tools Reference • Orchestrated Plans • Configuration • Release • FAQ

The Problem

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).

The Solution

Mission Control orchestrates isolated environments for your AI agents. Each job gets its own git worktree and 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.

How It Works

                          ┌─────────────────────────┐
                          │     Your Main Session    │
                          │   (Command Center)       │
                          └────────────┬────────────┘
                                       │
                          mc_launch / mc_plan
                                       │
                   ┌───────────────────┼───────────────────┐
                   │                   │                   │
            ┌──────┴──────┐     ┌──────┴──────┐     ┌──────┴──────┐
            │   Job A     │     │   Job B     │     │   Job C     │
            │  Worktree   │     │  Worktree   │     │  Worktree   │
            │  + tmux     │     │  + tmux     │     │  + tmux     │
            └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
                   │                   │                   │
                   └───────────────────┼───────────────────┘
                                       │
                               mc_diff / mc_pr
                               mc_merge / mc_sync
                                       │
                                       ▼
                              ┌─────────────────┐
                              │   Main Branch   │
                              └─────────────────┘

1. Launch — mc_launch creates a git worktree + tmux session and starts an AI agent inside it
2. Monitor — The background monitor polls every 10s, tracking output, idle state, and pane death
3. Observe — Use mc_status, mc_capture, or mc_attach to check on progress
4. Integrate — Use mc_diff to review, mc_pr to create a PR, mc_merge to merge, or mc_sync to rebase

Quick Start

Prerequisites

Installation (OpenCode Plugin)

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.

Your First Job

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

More Usage Examples

1) Run two tasks in parallel, then compare output

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")

2) Monitor everything in one command

You: "What's happening right now?"

AI: → mc_overview()

3) Stop a runaway job and clean up

You: "Kill the experiment and remove its worktree."

AI: → mc_kill(name: "wild-experiment")
    → mc_cleanup(name: "wild-experiment", deleteBranch: true)

4) Keep a long job current with main

You: "Rebase the feature job onto latest main."

AI: → mc_sync(name: "feature-checkout", strategy: "rebase")

5) Orchestrate dependent work automatically

AI: → mc_plan(
      name: "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.

Tools Reference

Job Lifecycle

mc_launch

Launch a new parallel AI coding session in an isolated worktree.

What happens on launch:

1. Creates a new git worktree on a dedicated branch
2. Runs post-create hooks (copy files, create symlinks, run commands)
3. Spins up a tmux session or window
4. Starts opencode --prompt '...' inside the tmux pane
5. Sets up pane-died hook for completion detection
6. Registers the job for background monitoring

mc_jobs

List all jobs with their current status.

mc_status

Get detailed status of a specific job including branch, worktree path, tmux target, duration, and mode.

mc_capture

Capture the last N lines of terminal output from a job's tmux pane.

mc_attach

Get the tmux command to attach to a job's terminal session.

mc_kill

Stop a running job by terminating its tmux session/window.

mc_cleanup

Remove finished job worktrees and metadata.

Monitoring & Reporting

mc_overview

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.

mc_report

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.

Reports are used by the monitoring system to:

• Trigger notifications (e.g., when an agent reports blocked or needs_review)
• Signal explicit completion (a completed report immediately marks the job as done)
• Provide progress visibility via mc_status and mc_overview

Git Workflow

mc_diff

Compare a job's branch against the base branch.

mc_pr

Push the job's branch and create a GitHub Pull Request. Requires the gh CLI to be authenticated.

mc_sync

Pull the latest changes from the base branch into a job's worktree.

mc_merge

Merge a job's branch back into the main worktree.

Orchestrated Plans

For workflows with dependencies between jobs, the Plan System manages the full lifecycle — from parallel execution to merge ordering to PR creation.

mc_plan

Create and start a multi-job orchestrated plan.

JobSpec fields:

Plan Modes

Plan Lifecycle

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)
  │
  │   ┌──────── 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

Plan Control Tools

mc_plan_status

Show the current state of the active plan — job statuses, progress, and any checkpoints.

No parameters.

mc_plan_approve

Approve a copilot plan to start execution, or clear a supervisor checkpoint to continue.

mc_plan_cancel

Cancel the active plan. Stops all running jobs, deletes the integration branch, and cleans up state.

No parameters.

Example: Orchestrated Plan

AI: I'll create a plan for the dashboard feature with proper dependencies.

→ mc_plan(
    name: "dashboard-feature",
    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
  • dashboard-ui and docs wait for api-endpoints — then run in parallel
  • Once all merge successfully, a PR is created automatically

Merge Train

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}):

1. Merge — git merge --no-ff {job-branch} into the integration worktree
2. Test — If a testCommand is configured (or detected from package.json), it runs after each merge
3. Rollback — If tests fail or time out, the merge is automatically rolled back (git merge --abort or git reset --hard HEAD~1)
4. 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.

Slash Commands

These commands run directly in the OpenCode chat — instant execution without an AI roundtrip (except /mc-launch, which delegates to the AI).

Monitoring System

Mission Control runs an active background monitor — not a passive wrapper.

How Monitoring Works

Hooks & Lifecycle

Configuration

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"
  }
}

Configuration Reference

Worktree Setup

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 for node_modules, .cache)
• commands — Runs shell commands after setup (great for bun install, pip install -e .)

Per-job parameters are merged with the global worktreeSetup config.

OMO Integration

If you use Oh-My-OpenCode (OMO), Mission Control unlocks advanced execution modes for spawned agents. These are optional — everything works without OMO installed.

OMO detection is automatic — Mission Control checks your opencode.json for the oh-my-opencode plugin.

FAQ

Q: Where are worktrees stored? A: By default in ~/.local/share/opencode-mission-control/{project}/. They are real git worktrees — fully functional working copies.

Q: Can I use this without tmux? A: No. tmux is the backbone of session isolation, monitoring, idle detection, and output capture. It's a hard requirement.

Q: Does it work with VS Code / Cursor? A: Yes. You can open any job's worktree directory in your editor. The AI agents run in background tmux sessions independently.

Q: What happens if my computer restarts? A: Mission Control will detect dead tmux panes on the next poll and mark those jobs as failed. Use mc_cleanup to clean up.

Q: How many jobs can I run at once? A: 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.

Q: What if two jobs edit the same file? A: Since each job has its own worktree, there are no runtime conflicts. Conflicts surface at merge time — either via mc_merge or the plan's merge train.

Q: Can I attach to a job's terminal while it's running? A: Yes. Use mc_attach to get the tmux command, then run it in your terminal. You'll see the live AI session.

Q: How does the plan merge train handle test failures? A: 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).

Q: Is this built by the OpenCode team? A: No. This is an independent community plugin — not affiliated with or endorsed by the OpenCode team.

Q: Do I need to manually install this with npm first? A: Usually no. Put it in opencode.json and let OpenCode handle plugin installation. Manual npm install is mostly for local development or debugging.

Release & npm Deploy

This repo uses semantic versioning with semantic-release for automated npm releases.

How it works:

1. Merge a Conventional Commit into main (for example: feat:, fix:, or BREAKING CHANGE:).
2. GitHub Actions runs build + tests.
3. semantic-release calculates 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.

Development

bun install
bun run build
bun test

Contributing

Found a bug? Have an idea? Check out CONTRIBUTING.md.

License

MIT

Inspired By

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