opencode-goku-team

OpenCode plugin that injects a goku primary orchestrator agent and four subagents: explore, planner, developer, and reviewer.

By default, the plugin also injects a local MCP server named codegraph unless cfg.mcp.codegraph is already defined elsewhere in your opencode config.

Installation

Install and reference it from opencode.json through the plugin array.

The default MCP integration requires a codegraph executable on your PATH. Install the codegraph CLI before relying on the default codegraph serve --mcp command.

As an npm package:

{
  "plugin": [
    "opencode-goku-team"
  ]
}

If you want to pass plugin options, use the tuple form:

{
  "plugin": [
    [
      "opencode-goku-team",
      {
        "agents": {
          "goku": { "model": "openai/gpt-5.4", "variant": "medium" }
        }
      }
    ]
  ]
}

As a local plugin from ~/.config/opencode/plugin/goku/index.ts, reference it from ~/.config/opencode/opencode.json:

{
  "plugin": [
    "./plugin/goku/index.ts"
  ]
}

Or with options:

{
  "plugin": [
    [
      "./plugin/goku/index.ts",
      {
        "agents": {
          "goku": { "model": "openai/gpt-5.4", "variant": "medium" }
        }
      }
    ]
  ]
}

What It Provides

The plugin injects five agents into opencode:

• goku: the primary orchestrator agent. This is the default agent unless you override defaultAgent.
• explore: codebase exploration and context gathering.
• planner: planning and task breakdown.
• developer: implementation and debugging.
• reviewer: review for bugs, regressions, and missing coverage.

Configuration

OpenCode config does not allow unknown top-level fields, so this plugin must be configured through plugin options inside the plugin array.

Default behavior

No options are required. The plugin injects all five agents, sets the default agent to goku, and adds a default local codegraph MCP server when cfg.mcp.codegraph is not already present.

{
  "plugin": [
    "opencode-goku-team"
  ]
}

The injected MCP entry is:

{
  "mcp": {
    "codegraph": {
      "type": "local",
      "command": ["codegraph", "serve", "--mcp"],
      "enabled": true
    }
  }
}

If you already define mcp.codegraph in opencode.json, the plugin leaves that entry untouched.

Disable the default codegraph MCP integration

Use false when you want the plugin to write an explicit disabled entry instead of the default local server:

{
  "plugin": [
    [
      "opencode-goku-team",
      {
        "codegraph": false
      }
    ]
  ]
}

This form is also accepted:

{
  "plugin": [
    [
      "opencode-goku-team",
      {
        "codegraph": { "enabled": false }
      }
    ]
  ]
}

Customize the injected codegraph MCP server

When you want the plugin to manage the server but override the default launch details, use the schema-safe command, cwd, timeout, and environment keys:

{
  "plugin": [
    [
      "opencode-goku-team",
      {
        "codegraph": {
          "command": ["codegraph", "serve", "--mcp", "--stdio"],
          "cwd": "~/src/my-monorepo",
          "timeout": 15000,
          "environment": {
            "CODEGRAPH_CACHE_DIR": "~/.cache/codegraph"
          }
        }
      }
    ]
  ]
}

Unknown codegraph option keys are ignored so the plugin only writes fields that match opencode's config schema.

Set the goku primary agent's model and variant

Use the agents form when you want explicit per-agent configuration.

{
  "plugin": [
    [
      "opencode-goku-team",
      {
        "agents": {
          "goku": { "model": "openai/gpt-5.4", "variant": "medium" }
        }
      }
    ]
  ]
}

Configure each subagent's model and variant

{
  "plugin": [
    [
      "opencode-goku-team",
      {
        "agents": {
          "goku": { "model": "openai/gpt-5.4", "variant": "medium" },
          "explore": { "model": "opencode-go/deepseek-v4-flash", "variant": "medium" },
          "planner": { "model": "openai/gpt-5.5", "variant": "xhigh" },
          "developer": { "model": "openai/gpt-5.4", "variant": "high" },
          "reviewer": { "model": "openai/gpt-5.5", "variant": "xhigh" }
        }
      }
    ]
  ]
}

Use the models and variants shorthand

The shorthand form is equivalent, but split across two maps.

{
  "plugin": [
    [
      "opencode-goku-team",
      {
        "models": {
          "goku": "openai/gpt-5.4",
          "explore": "opencode-go/deepseek-v4-flash",
          "planner": "openai/gpt-5.5",
          "developer": "openai/gpt-5.4",
          "reviewer": "openai/gpt-5.5"
        },
        "variants": {
          "goku": "medium",
          "explore": "medium",
          "planner": "xhigh",
          "developer": "high",
          "reviewer": "xhigh"
        }
      }
    ]
  ]
}

Change the default agent via defaultAgent

By default, the plugin sets opencode's default_agent to goku. Override that with defaultAgent if you want a different starting agent.

{
  "plugin": [
    [
      "opencode-goku-team",
      {
        "defaultAgent": "developer",
        "agents": {
          "goku": { "model": "openai/gpt-5.4", "variant": "medium" },
          "developer": { "model": "openai/gpt-5.4", "variant": "high" }
        }
      }
    ]
  ]
}

Compatibility wrapper

For compatibility, the plugin also accepts the same options wrapped in a goku key:

{
  "plugin": [
    [
      "opencode-goku-team",
      {
        "goku": {
          "defaultAgent": "developer",
          "models": {
            "goku": "openai/gpt-5.4",
            "developer": "openai/gpt-5.4"
          },
          "variants": {
            "goku": "medium",
            "developer": "high"
          }
        }
      }
    ]
  ]
}

Options Reference

type Options = {
  defaultAgent?: string
  agents?: Record<string, { model?: string; variant?: string }>
  models?: Record<string, string>
  variants?: Record<string, string>
  codegraph?:
    | false
    | {
        enabled?: boolean
        command?: string[]
        cwd?: string
        timeout?: number
        environment?: Record<string, string>
      }
}

• defaultAgent?: string: sets opencode's default_agent. Defaults to "goku" when omitted.
• agents?: Record<string, { model?: string; variant?: string }>: explicit per-agent overrides. Valid keys are goku, explore, planner, developer, and reviewer.
• models?: Record<string, string>: shorthand model overrides by agent name.
• variants?: Record<string, string>: shorthand variant overrides by agent name.
• codegraph?: false | { enabled?: boolean; command?: string[]; cwd?: string; timeout?: number; environment?: Record<string, string> }: controls the plugin-managed mcp.codegraph entry. The plugin preserves any existing cfg.mcp.codegraph; otherwise it injects the default local server or an explicit disabled entry.

If both forms are present for the same agent, agents[agentName].model and agents[agentName].variant take precedence over models[agentName] and variants[agentName].

For compatibility, wrapping these options in a top-level goku key is also accepted, but the direct form is preferred.

Agent Templates

Agent definitions live in agents/*.md. Each file uses opencode-style frontmatter plus a markdown prompt body. The plugin reads these files at startup and injects them into cfg.agent.

Important Notes

• opencode config must be passed as plugin options. Do not add unknown top-level fields to opencode.json.
• Restart opencode after changing plugin config, this plugin, or any agent template.
• The plugin reads agents/*.md at startup, so template changes are only picked up on the next restart.
• The codegraph MCP integration is also loaded from config at startup, so option changes require a full opencode restart.