Skip to content
maestria

Configuration

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

Per-Agent Models

Section titled “Per-Agent Models”
{
  "agents": {
    "adventurer": { "model": "<model-id>" },
    "reviewer": { "model": "<model-id>#high" },
  },
}

Edit the global config (opencode.jsonc or opencode.json in ~/.config/opencode/, or $XDG_CONFIG_HOME/opencode/ when set) or the project config (.opencode/opencode.jsonc, .opencode/opencode.json, or opencode.json(c) at the project root). Unmentioned agents keep their existing assignments.

Use <provider>/<model-id> with an explicit model ID copied from OpenCode’s live model list, optionally followed by #<variant>: model IDs, availability, pricing, and aliases vary. OpenCode still accepts the V1 agent.<name>.model form; when both are set, the agents value wins (V1 migration guide).

Model Inheritance

Section titled “Model Inheritance”

Model assignment follows a chain. In OpenCode V2, a primary agent uses the session’s selected model, and a subagent without its own model inherits the model of the session that launched it (agents documentation).

The 4 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. It writes agents.<name>.model and removes a V1 agent.<name>.model for the same agent so the two cannot conflict:

Terminal window
npx maestria@latest configure opencode --global --set adventurer=<model-id>,reviewer=<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 agents.<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. Disabled keywords are no longer detected in prompts; their slash commands stay available:

{
  "plugins": [
    {
      "package": "@maestria/opencode",
      "options": { "modes": { "disabledKeywords": ["blitz"] } },
    },
  ],
}

Invalid options are logged and ignored, and the plugin runs with defaults.

Mode detection and precedence are documented under Modes.