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 how to make selective assignments without choosing a provider-specific preset.

Model choice affects every delegated stage

The orchestrator’s model is inherited by specialists unless you override them. A different model on the orchestrator can therefore be used for reconnaissance, implementation, review, and retries. Read When to use Maestria before assigning the same model to every agent.

Why Set Per-Agent Models

Model IDs, availability, pricing, aliases, and platform support vary. Avoid generic cost or quality presets. Instead, choose an explicit model ID from OpenCode’s normal, live model list and assign it only where you have a clear reason.

You can assign a model to any specialist. Unmentioned specialists keep their existing assignments.

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:

{
  "agent": {
    "adventurer": { "model": "<model-id>" },
    "writer": { "model": "<model-id>" },
  },
}

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

Model ID format

Use <provider>/<model-id>.

Value	Description
<model-id>	An explicit ID copied from OpenCode’s live list

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 when you want all specialists to inherit it.
• Override selectively when a specialist needs a different model. Unmentioned specialists keep their existing assignments.

Tip

If you want every specialist on the same model, just set

agent.orchestrator.model

. No need to repeat it for all 8 agents. Only add entries for the agents you want to diverge.

Selective assignment

Use the CLI to validate the model ID against OpenCode’s live model list before writing it:

maestria configure opencode --global --set adventurer=<model-id>,writer=<model-id>

The CLI changes only the named agents. Configuration through maestria configure currently supports OpenCode, Pi, and OMP.

Model Field in Markdown Frontmatter

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

---
name: my-custom-agent
model: <model-id>
---

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 different explicit model IDs for different projects from the same global install.