Skip to content
maestria

Configuration

The @maestria/opencode plugin registers 8 agents with no model overrides, so each runs on the model OpenCode assigns by default. Overrides use the standard agent.<name>.model path, which works for any agent.

Per-Agent Models

Section titled “Per-Agent Models”
{
  "agent": {
    "adventurer": { "model": "<model-id>" },
    "writer": { "model": "<model-id>" },
  },
}

Edit either ~/.config/opencode/opencode.jsonc (global) or .opencode/opencode.jsonc (project-level). Unmentioned agents keep their existing assignments.

Use <provider>/<model-id> with an explicit model ID copied from OpenCode’s live model list: model IDs, availability, pricing, and aliases vary.

Model Inheritance

Section titled “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.

The 7 specialists are subagents of the orchestrator, so they inherit the orchestrator’s model unless overridden individually. Read When to use maestria before assigning the same model to every agent.

Selective Assignment

Section titled “Selective Assignment”

The CLI validates a model ID against OpenCode’s live model list and changes only the named agents:

Terminal window
npx maestria@latest configure opencode --global --set adventurer=<model-id>,writer=<model-id>

See the configure reference for supported platforms and options.

Model Field in Markdown Frontmatter

Section titled “Model Field in Markdown Frontmatter”

Custom agents defined locally can set the model in the agent’s Markdown frontmatter:

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

This works the same as the agent.<name>.model config entry.

Project-Level Config

Section titled “Project-Level Config”

Project config (.opencode/opencode.jsonc) merges with global config (~/.config/opencode/opencode.jsonc); project settings take precedence.

Disabling Workflow Modes

Section titled “Disabling Workflow Modes”

modes.disabledKeywords accepts a denylist of mode keywords in the plugin options:

{
  "plugin": ["@maestria/opencode", { "modes": { "disabledKeywords": ["blitz"] } }],
}

Mode detection and precedence are documented under Modes.