# Configuration

The `@maestria/opencode` plugin registers 8 agents with no model overrides. Each agent runs on whatever model OpenCode assigns by default. You can change this by setting per-agent models in your OpenCode config.

This page covers how the model hierarchy works and what assignments make sense for each specialist.

## Why Set Per-Agent Models

Different specialists benefit from different models. A fast, cheap model works for file-scanning tasks. A more capable model matters where output quality is critical - code generation, review, and architecture.

Matching models to agent roles lets you tune cost and latency:

- **Adventurer** - fast and cheap for read-only searches
- **Builder** - capable for code generation quality
- **Reviewer** - capable for critical quality gates
- **Orchestrator** - balanced for task routing and coordination

## How It Works

The plugin registers agents without a `model` field in their frontmatter. OpenCode's config merge applies your overrides from `opencode.jsonc` on top of the defaults. No conflict, no plugin changes needed.

The model property follows OpenCode's standard agent config path: `agent.<name>.model`. The same path works for any agent, not just the ones from this plugin.

## Syntax

Add agent model overrides to your OpenCode config:

```jsonc
{
  "agent": {
    "adventurer": { "model": "anthropic/claude-haiku-4-20250514" },
    "builder": { "model": "openai/gpt-4o" },
    "reviewer": { "model": "openai/gpt-4o" },
    "orchestrator": { "model": "anthropic/claude-sonnet-4-20250514" },
  },
}
```

You can edit either `~/.config/opencode/opencode.jsonc` (global) or `.opencode/opencode.jsonc` (project-level).

### Model ID format

Use `<provider>/<model-id>`.

| Provider  | Example ID                           |
| --------- | ------------------------------------ |
| Anthropic | `anthropic/claude-sonnet-4-20250514` |
| Anthropic | `anthropic/claude-haiku-4-20250514`  |
| OpenAI    | `openai/gpt-4o`                      |

## Subagent Model Inheritance

Model assignment follows a chain. From the OpenCode documentation:

> If you don't specify a model, primary agents use the globally configured model while subagents will use the model of the primary agent that invoked the subagent.

Maestria's 7 specialists are subagents of the orchestrator. This means they inherit the orchestrator's model unless you override a specialist individually. So setting a model on the orchestrator affects all specialists by default.

This matters for your config strategy:

- **Set one model** on the orchestrator. All specialists inherit it. Simple, uniform behavior.
- **Override selectively** when a specialist needs a different model. For example, use a cheaper model on adventurer and keep the rest on the orchestrator's model.
**Tip:** If you want every specialist on the same model, just set{' '}
  ```jsonc
agent.orchestrator.model
```. No need to repeat it for all 8 agents. Only
  add entries for the agents you want to diverge.

## Suggested Assignments

These are starting points, not rules. Your optimal config depends on which models you have access to and what trade-offs you prefer between speed and quality.

| Agent        | Suggested model strategy                         | Reason                                                    |
| ------------ | ------------------------------------------------ | --------------------------------------------------------- |
| Orchestrator | Balanced (Claude Sonnet 4, GPT-4o)               | Needs good judgment across varied routing decisions       |
| Adventurer   | Fast/cheap (Claude Haiku 4, GPT-4o-mini)         | Read-only searches, high throughput, latency matters      |
| Architect    | Capable (Claude Sonnet 4, GPT-4o)                | Trade-off analysis and design reasoning                   |
| Builder      | Capable (Claude Sonnet 4, GPT-4o)                | Code generation quality is the main output                |
| Diagnose     | Capable (Claude Sonnet 4, GPT-4o)                | Deep reasoning and long-context tracing                   |
| Planner      | Capable (Claude Sonnet 4, GPT-4o)                | Structured multi-phase output                             |
| Reviewer     | Most capable available (Claude Sonnet 4, GPT-4o) | Critical quality gate - correctness, edge cases, security |
| Writer       | Balanced (Claude Sonnet 4, GPT-4o)               | Prose quality with moderate latency                       |
**Note:** The model IDs above are examples. Check OpenCode's documentation for the latest available models
  and their exact identifiers. Model availability depends on your API provider and plan.

## Model Field in Markdown Frontmatter

For custom agents you define locally, you can also set the model directly in the agent's Markdown frontmatter:

```markdown
---
name: my-custom-agent
model: openai/gpt-4o
---
```

This works the same as the `agent.<name>.model` config entry. Frontmatter is useful when the agent file is self-contained, like a project-specific agent checked into your repo.

## Managing Config Across Projects

You can keep different model configs for different projects. Project-level config (`.opencode/opencode.jsonc`) merges with global config (`~/.config/opencode/opencode.jsonc`). Project settings take precedence.

This lets you use expensive models for your main project and cheaper models for side projects, all from the same global install.