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 |

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 | | 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) | | 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 | Model ID (provider/model) | | temperature | number (0-2) | Model temperature | | variant | string | Variant hint (e.g. "pro", "flash") | | options | object | Provider-specific model options | | displayName | string | Custom agent display name |

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 usage instructions. Subagents can reference them right away.
• Missing capabilities: If a useful capability is found but not yet installed, the orchestrator shows the install command before moving on.

Discovery runs automatically for non-trivial tasks.

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> - Add OpenCode Go account
• /subscriptions add-neuralwatt <name> <api-key> - Add Neuralwatt account
• /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 | | Neuralwatt | neuralwatt | REST API (credits, kWh, token usage) | API key | | 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.

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

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