opencode-multiagent

opencode-multiagent

opencode-multiagent is a TypeScript OpenCode plugin package for running a disciplined multi-agent control plane through the standard OpenCode plugin system.

• 4 primary agents: lead, critic, planner, executor
• 16 subagents for coding, review, research, docs, and repo mapping
• plugin-managed MCP defaults and MCP tool enforcement
• central agent settings, profiles, telemetry, file-lock, and QA reminder guards
• npm-loaded plugin model through opencode.json

Install

For plugin consumers, the primary integration is opencode.json.

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-multiagent"]
}

OpenCode resolves the package from the plugin array and loads the plugin from the package export.

Example configs:

• examples/opencode.json
• examples/opencode.with-overrides.json

Development

For working on this plugin package itself:

npm install
npm run ci:check

Local OpenCode development can use a linked package or a local package path in opencode.json while iterating.

Migration from the old setup

If your old opencode.json manually carried MCP servers, plugin-managed agents, or broad permission defaults, simplify it.

Recommended migration:

• Add "plugin": ["opencode-multiagent"]
• Remove duplicated mcp definitions unless you are intentionally overriding a bundled server
• Remove duplicated bundled agent entries unless you are intentionally overriding a field like steps
• Remove broad tool permission blocks that were only compensating for the old flat config

Minimal target:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-multiagent"]
}

Override example:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-multiagent"],
  "agent": {
    "lead": {
      "steps": 650
    }
  }
}

Architecture

Primary agents

• lead - single entry point, lifecycle owner, 4-tier triage
• critic - challenge mode plus inspection mode
• planner - durable plan authoring
• executor - task orchestration and validation tiers

Subagents

• scout
• worker, heavy-worker, deep-worker, ui-worker, ui-heavy-worker, quick
• reviewer, validator, qa
• advisor, strategist, auditor, devil
• scribe
• librarian

Lead triage

• Tier 0 - trivial work -> executor
• Tier 1 - bounded work -> critic then executor
• Tier 2 - complex work -> critic then planner then executor
• Tier 3 - investigation or repo-memory work -> critic inspection mode

Plugin responsibilities

The plugin config hook:

• injects bundled markdown agents and commands
• applies central agent setting overrides from defaults/agent-settings.json
• injects plugin-managed MCP defaults from defaults/mcp-defaults.json
• blocks disallowed MCP tool usage using compiled per-agent permission rules
• disables native user-facing OpenCode agents when the plugin-managed replacements are active
• prefers lead as default_agent

The runtime hook layer also provides:

• telemetry JSONL logging
• file-lock protection for overlapping edits across sessions
• repeated QA handoff reminders
• quality reminders for verification-like follow-up
• supervision for child sessions

Plugin-owned MCP behavior

Bundled MCP defaults:

• code_index
• repo
• context7
• exa
• gh_grep
• github

Behavior:

• if the host config does not define one of these servers, the plugin injects its bundled default
• if the host config already defines one of these servers, the plugin does not overwrite it
• agent access is shaped by bundled frontmatter permissions and re-checked in runtime hooks

That means the plugin owns the baseline MCP layer, while the host config remains the override layer.

Runtime config

User overrides live under ~/.config/opencode/plugins/:

• opencode-multiagent.flags.json
• opencode-multiagent.agent-settings.json
• opencode-multiagent.profiles.json

Bundled defaults live in defaults/ and are merged conservatively at runtime.

Scripts

npm run typecheck
npm run validate-config
npm run config-server
npm run telemetry-report
npm run ci:check
npm run pack:dry-run

Release model

• CI is npm-based
• publish flow is npm trusted publishing ready
• plugin consumption stays opencode.json -> plugin
• the package is source-first TypeScript; OpenCode can load the exported TypeScript entry directly

Publishing

This repository is set up for npm trusted publishing through GitHub Actions OIDC.

Before any release:

npm run ci:check
npm run pack:dry-run

First publish

The first npm publish must be done manually from the repository root because trusted publishing cannot create a brand-new package on npm by itself.

npm whoami
npm publish --access public

Do not use local provenance for the first publish. Provenance is generated later by the GitHub Actions publish workflow.

If npm requires browser or OTP confirmation, complete that locally first.

Trusted publisher setup

After the first successful publish, create the npm trusted publisher mapping for this repository:

npx -y npm@11.11.0 trust github opencode-multiagent --repo vaur94/opencode-multiagent --file publish.yml

The workflow filename must stay publish.yml on npm's side, not .github/workflows/publish.yml.

Workflow behavior

• GitHub release published events perform a real npm publish --provenance --access public
• manual workflow_dispatch runs verification by default and only publish when the publish input is enabled
• release tags must match v<package.json version> before the publish step can run

Notes

• no file-copy install or update workflow remains
• no bundled test suite remains; validation is static and structural by design
• this package is now aligned to the standard OpenCode plugin loading model instead of the old copied-global-file model