opencode-dux

Agent orchestration, management, and operations plugin for OpenCode. Routes tasks to specialized agents automatically.

Quick Start

1. Add to ~/.config/opencode/opencode.json and ~/.config/opencode/tui.json:

{ "plugin": ["opencode-dux@latest"] }

2. Create ~/.config/opencode/opencode-dux.jsonc:

{
  "$schema": "https://raw.githubusercontent.com/bakhtiar-personal-work/opencode-dux/master/opencode-dux.schema.json",
  "preset": "default",
  "presets": {
    "default": {
      "orchestrator": { "model": "opencode-go/deepseek-v4-flash" },
      "oracle": { "model": "opencode-go/deepseek-v4-flash" },
      "explorer": { "model": "opencode-go/deepseek-v4-flash" },
      "librarian": { "model": "opencode-go/deepseek-v4-flash" },
      "designer": { "model": "opencode-go/mimo-v2.5-pro" },
      "fixer": { "model": "opencode-go/deepseek-v4-flash" }
    }
  }
}

3. Authenticate: opencode auth login

Auto-Update

The plugin checks for updates when OpenCode starts up. If an update is available it downloads in the background.

How it works

• When the app starts the plugin checks for a newer version
• If found it downloads the update silently in the background
• A popup shows whether the update succeeded or failed
• Restart OpenCode to apply the new version

Installation requirement

Auto-update works with "opencode-dux" and "opencode-dux@latest". OpenCode treats them the same.

{ "plugin": ["opencode-dux"] }

Keep "opencode-dux" without a version in your config. Pinning a version like "[email protected]" turns off auto-update.

Agents

| Agent | Role | When Used | | ---------------- | -------------------- | ----------------------------------------------------- | | Orchestrator | Master delegator | Routes tasks, strategic coordination | | Explorer | Codebase search | File discovery, pattern matching | | Oracle | Architecture & debug | Trade-offs, root cause analysis | | Librarian | External research | Documentation lookup, web search | | Designer | UI/UX | Frontend, styling, accessibility | | Fixer | Implementation | Scoped code changes, tests | | Steward | Repository rules | Manages .docs/, .opencode/, .cursor/rules, etc. | | Interpreter | Image analysis | Vision-capable model for attached screenshots |

Routing notes:

• Bug fixes go to @oracle first when they need diagnosis, root-cause analysis, tradeoff evaluation, or multi-file reasoning. @fixer implements the approved plan.
• Before any non-mechanical @fixer implementation run, the orchestrator must first present the proposed fix/plan to the user and get explicit approval. The user can choose the implementation path, request changes, or stop before code is modified.
• Only purely mechanical edits such as typos, obvious single-line fixes, or user-specified exact changes may bypass @oracle and go straight to @fixer.

Configuration

Config file: ~/.config/opencode/opencode-dux.jsonc

Merged from two locations, project overrides user:

| Location | Path | | ----------- | ---------------------------------------- | | User | ~/.config/opencode/opencode-dux.jsonc | | Project | <project>/.opencode/opencode-dux.jsonc |

Config options

| Field | Type | Default | Description | | ------------------------------------ | ---------- | ------- | --------------------------------------------- | | preset | string | - | Active preset name | | customInstruction | string | - | Text prepended verbatim to orchestrator system prompt. Can live at root or inside active preset; root wins. | | presets | object | {} | Named model configurations per agent | | agents | object | {} | Per-agent overrides on top of active preset | | sessionManager.maxSessionsPerAgent | number | 2 | Max concurrent sessions per agent type (1-10) | | sessionManager.readContextMinLines | number | 10 | Min lines threshold for read context tool | | sessionManager.readContextMaxFiles | number | 8 | Max files per read context batch | | todoContinuation.maxContinuations | number | 5 | Max consecutive auto-continuations (1-50) | | todoContinuation.autoEnable | boolean | false | Auto-enable when enough todos exist | | contextPressure.enabled | boolean | true | Warn when context usage is high | | contextPressure.warnThresholdPct | number | 75 | Trigger at this context usage % (1-99) | | handoffArtifacts.location | "project" or "cache" | "project" | "project" keeps .opencode-dux/ in repo. "cache" stores artifacts outside repo in app cache. | | websearch.provider | string | "exa" | "exa" or "tavily" | | setDefaultAgent | boolean | true | Sets default_agent to orchestrator | | autoUpdate | boolean | true | Auto-update when loaded via npm name | | disabledMcps | string[] | [] | Disable built-in MCPs by name |

Per-agent options

| Field | Type | Description | | ------------- | -------------- | -------------------------------------- | | model | string | Simple form for all agents | | thinking | boolean | Simple form: enable/disable variants | | variants | string[] | Simple form: ordered allowed variants | | default | object | Default tier: model, optional thinking and ordered variants | | smart | object | Oracle-only higher-capability tier with the same fields | | temperature | number (0-2) | Model temperature | | options | object | Provider-specific model options | | displayName | string | Custom agent display name |

Simple top-level form applies to:

• orchestrator
• explorer
• librarian
• designer
• fixer
• steward
• interpreter

For those agents, use top-level model, optional thinking, optional variants, plus any other direct options like temperature.

variants are ordered from lower to higher thinking effort. When omitted, opencode-dux leaves variant selection to orchestrator/provider default. thinking: false suppresses variant field. Legacy model and options.smart remain supported.

Standard agent example:

{
  "presets": {
    "default": {
      "orchestrator": {
        "model": "neuralwatt/moonshotai/Kimi-K2.7-Code",
        "thinking": true,
        "variants": ["high"]
      },
      "explorer": {
        "model": "opencode-go/mimo-v2.5"
      },
      "librarian": {
        "model": "opencode-go/mimo-v2.5"
      },
      "designer": {
        "model": "neuralwatt/glm-5.2",
        "thinking": true,
        "variants": ["high", "max"],
        "temperature": 0.3
      },
      "fixer": {
        "model": "opencode-go/mimo-v2.5-pro",
        "thinking": true,
        "variants": ["high"]
      },
      "steward": {
        "model": "opencode-go/mimo-v2.5"
      },
      "interpreter": {
        "model": "opencode-go/minimax-m3"
      }
    }
  }
}

oracle is special. Its top-level model / thinking / variants act as default tier, and optional smart adds higher-capability routing.

Oracle example:

{
  "presets": {
    "default": {
      "oracle": {
        "model": "neuralwatt/glm-5.2",
        "thinking": true,
        "variants": ["high", "max"],
        "smart": {
          "model": "openai/gpt-5.4",
          "thinking": true,
          "variants": ["high", "xhigh"]
        }
      }
    }
  }
}

Automatic Skill & MCP Discovery

The orchestrator discovers skills and MCPs before delegating to subagents:

• Skills: Before @oracle, @designer, or @librarian runs on a non-trivial task, the orchestrator calls discover_skills and discover_mcp_servers in parallel. Results are cached for 24 hours.
• Installed capabilities: Relevant installed skills and MCPs are injected into the delegation prompt with their name, description, relevance, and explicit usage instructions. For high-relevance matches, orchestrator names exact skills/MCPs, states why they apply, and tells subagents to use them directly instead of treating them as optional context.
• Missing capabilities: If a useful capability is found but not yet installed, the orchestrator shows the install command before moving on.
• Approval gate: For any new non-mechanical @fixer run, the orchestrator must include an explicit implementation-authorization block derived from the latest user approval. The delegate runtime rejects missing authorization, so prompt-only drift cannot silently bypass confirmation.

Discovery runs automatically for non-trivial tasks.

Handoff Artifacts

Delegated subagent runs now persist handoff artifacts for later reuse:

Set it like this in opencode-dux.jsonc:

{
  "handoffArtifacts": {
    "location": "project" // or "cache"
  }
}

What to put:

• "project": current behavior. Creates .opencode-dux/ inside repo.

• "cache": stores artifacts outside repo so project tree stays clean.

• handoffArtifacts.location: "project" (default):

  • Root: .opencode-dux/
  • Child session artifacts: .opencode-dux/<agent>/<sessionId>_<yyyymmdd-hhmmss>_<slug>.md
  • Orchestrator index: .opencode-dux/orchestrator/<orchestratorSessionId>.md

• handoffArtifacts.location: "cache":

  • Windows: %LOCALAPPDATA%/opencode-dux/artifacts
  • non-Windows: ~/.cache/opencode-dux/artifacts
  • Prompts and envelopes use absolute artifact paths in this mode

Behavior:

• Blocking delegate_subagent results return a compact envelope with artifact paths instead of always echoing the full raw child output.
• New @fixer runs require an explicit implementation-authorization block from the orchestrator. In practice this means the user must have already approved the proposed plan, unless the change is a true mechanical-edit exception.
• For true "run these several searches now and wait for all of them" behavior, the orchestrator uses batched blocking delegation internally rather than emitting separate blocking calls one-by-one.
• Parallel subagent fan-out should use mode: "fire_forget" for independent work streams. Read-only blocking delegations can overlap, but parallel @fixer batches should be collected first and then verified once by the orchestrator against the final combined repo state.
• If the orchestrator still emits multiple near-simultaneous blocking @fixer delegations from the same parent turn, the delegate runtime now coalesces them into one internal parallel batch instead of serializing them one-by-one.
• delegate_collect(session_id: "...") now waits by default for the internal completion event. Use wait: false only for an intentional non-blocking status probe; avoid repeated polling loops.
• Only orchestration-critical sections stay inline: needs_user, blocked, oracle plan, designer design_plan + implementation_notes, fixer summary + verification.
• The orchestrator system prompt keeps the routing control surface inline. Built-in tool availability does not let the orchestrator bypass specialist-only routing constraints.
• Resumed child sessions via continue_session_id append additional turns into the same artifact file.
• Artifacts are retained for 7 days and then pruned from the configured artifact root by the plugin.

Install new skills: npx skills add <owner/repo> --skill <skill-name> -g -a opencode -y

Skill discovery needs npx on your PATH for online searches (runs npx skills find <keywords>). Local skill checks work without it. MCP discovery uses the npm registry directly and does not need npx. Both check locally installed items first and skip online lookups when enough relevant matches are found.

Subscriptions / Account Commands

Manage API accounts from the OpenCode prompt with /subscriptions:

• /subscriptions list - View all accounts and their usage
• /subscriptions add-opencode-go <name> <workspace-id> <auth-cookie> <api-key> - Add OpenCode Go account
• /subscriptions add-neuralwatt <name> <api-key> - Add Neuralwatt account
• /subscriptions add-deepseek <name> <api-key> - Add DeepSeek account
• /subscriptions add-mimo <name> <api-key> <platform_ph> <serviceToken> <slh> <userId> - Add MiMo (Xiaomi) account (cookie values from browser DevTools)
• /subscriptions add-codex-device <name> - Add Codex (OpenAI) account via device auth
• /subscriptions switch <provider> <name> - Activate an account for a provider
• /subscriptions remove <provider> <name> - Delete an account
• /subscriptions refresh - Force refresh usage data

Supported providers

| Provider | Provider ID | Usage tracking | Auth method | | --------------- | ------------- | ----------------------------------------------------- | -------------------------- | | OpenCode Go | opencode-go | Dashboard scraping (rolling, weekly, monthly windows) | Workspace ID + auth cookie + API key | | Neuralwatt | neuralwatt | REST API (credits, kWh, token usage) | API key | | DeepSeek | deepseek | Official REST API (/user/balance) | API key | | MiMo | mimo | Platform API (balance, plan, AI Credits usage) | API key + cookie values | | Codex | codex | REST API (5H/7D rate limits, credits) | Device code auth (OAuth) |

Accounts are identified by provider and name. You can have accounts with the same name across different providers (e.g., "Main" for Codex, "Main" for Neuralwatt) without collisions. Remove a specific account with /subscriptions remove <provider> <name>.

Usage data appears in the TUI sidebar under API Usage.

All account credentials, API keys, tokens, and subscription data are stored locally on your machine. Nothing is sent to any external service or phoned home.

Codex device auth

Codex uses your ChatGPT account, not an API key. The device auth flow works from any terminal without needing a browser on the same machine.

1. Run /subscriptions add-codex-device <name>
2. Open the displayed URL in any browser and sign in with your ChatGPT account
3. Enter the one-time code shown in your terminal
4. Usage tracking starts immediately

Access tokens refresh automatically. If the refresh token expires (e.g., after a password change), run /subscriptions add-codex-device again.

MiMo authentication

MiMo uses both an API key (for inference) and cookie values (for usage tracking).

1. Run /subscriptions add-mimo <name> <api-key> <platform_ph> <serviceToken> <slh> <userId>
2. Get cookie values from browser DevTools → Application → Cookies → platform.xiaomimimo.com:
   • api-platform_ph
   • api-platform_serviceToken
   • api-platform_slh
   • userId

Usage tracking shows AI Credits (remaining / total) and balance in the TUI sidebar.

Prompt overrides

Place Markdown files in ~/.config/opencode/opencode-dux/:

• <agent>.md - Replace default prompt
• <agent>_append.md - Append to default prompt
• <preset>/<agent>.md - Preset-scoped prompts

Built-in MCPs

| MCP | Description | | ----------- | ---------------------------- | | websearch | Web search (Exa or Tavily) | | context7 | Library documentation lookup | | grep_app | GitHub code search |

Disable any: { "disabledMcps": ["grep_app"] }

Skill Discovery

The orchestrator uses discover_skills to find relevant skills before delegating. It checks local installs first, then falls back to online search:

• Local check: Scans ~/.config/opencode/skills/ and ~/.agents/skills/ for installed skills, scores them by relevance against task keywords
• Online search: If local results are insufficient, runs npx skills find <keywords> to search the registry
• MCP discovery: Searches the npm registry for matching MCP packages, scored by relevance against task keywords

How the full flow works:

1. Orchestrator calls discover_skills and discover_mcp_servers with task keywords (blocking, cached 24h)
2. Checks locally installed skills and MCPs first
3. If enough relevant local results are found it returns them and skips online search
4. Otherwise it searches online with npx skills find <keywords> for skills or npm registry for MCPs
5. Installed items are injected into delegation prompts with name, description, relevance, and usage instructions
6. Useful items that aren't installed yet are recommended to the user with install commands
7. The orchestrator carries its routing and approval policy inline, then delegates once the required gates are satisfied.

Install skills: npx skills add <owner/repo> --skill <skill-name> -g -a opencode -y

Skill discovery needs npx on your PATH for online searches (runs npx skills find <keywords>). Local skill checks and MCP discovery work without it.

Development

bun run build          # Build TypeScript to dist/
bun run typecheck      # Type checking
bun test               # Run tests
bun run check:ci       # Lint + format (CI mode)
bun run generate-schema  # Regenerate JSON schema from Zod

License

MIT