Configuration

Systematic works out of the box with sensible defaults, but it provides several ways to customize its behavior and content.

Plugin Configuration

You can customize the plugin by creating a configuration file. Systematic looks for configuration in three places:

1. Global: ~/.config/opencode/systematic.{json,jsonc}
2. Project-specific: .opencode/systematic.{json,jsonc}
3. Custom config directory: $OPENCODE_CONFIG_DIR/systematic.{json,jsonc}

When both .jsonc and .json exist in the same directory, .jsonc takes precedence and .json is silently ignored. This lets you add comments to your config without renaming or deleting the existing file.

Disabling Bundled Content

If you want to hide certain bundled skills or agents, you can list them in the disabled_* arrays:

{
  "disabled_skills": ["git-worktree"],
  "disabled_agents": []
}

Bundled Agent Overlays

Use top-level agents and categories maps to tune bundled Systematic agents without copying their markdown files into native OpenCode agent definitions.

{
  "categories": {
    // Applies to bundled agents in agents/review/*.md unless that agent has
    // been replaced by a native OpenCode agent with the same emitted key.
    "review": {
      "temperature": 0.1,
      "steps": 12
    }
  },
  "agents": {
    // Unqualified unique stem form.
    "security-sentinel": {
      // User or custom config only; project config cannot choose model/provider routing.
      "model": "anthropic/claude-sonnet-4-5",
      "variant": "thinking",
      "steps": 20
    },

    // Qualified form for the same inventory model: <category>/<agent-stem>.
    "workflow/systematic-implementer": {
      "mode": "subagent",
      "color": "cyan"
    }
  }
}

Valid category IDs are design, docs, document-review, research, review, and workflow. These IDs are V1 public API because broad policy overlays are a primary use case; future reorganizations must preserve aliases or ship migration warnings. Category overlays also apply to future bundled agents added to that category, so use them for policies you want to inherit broadly.

Exact agent overlays accept the unique file stem (security-sentinel) or the qualified key (review/security-sentinel). Pick one canonical form across all config sources. Systematic merges config sources before resolving aliases, so cross-source alias collisions like user agents.security-sentinel plus project agents.review/security-sentinel fail duplicate-target validation instead of silently overriding.

Supported overlay fields are model, variant, temperature, top_p, permission, mode, color, steps, hidden, exact-agent-only disable, and skills. color accepts #RGB, #RRGGBB, or OpenCode named color tokens matching [a-zA-Z][a-zA-Z0-9-]*; whitespace/freeform numeric strings are rejected.

skills is a Systematic-managed shortcut that writes OpenCode permission.skill rules using bundled skill frontmatter names such as ce:review. It is not a native OpenCode agent field. Because model and variant control provider routing/cost/privacy and permission/skills control tool access, those fields are accepted only from user config or $OPENCODE_CONFIG_DIR/systematic.json. Project config may tune non-sensitive presentation and runtime fields such as temperature, top_p, mode, color, steps, hidden, or exact-agent disable, but it cannot choose model/provider routing, tune variant, or loosen permission/capability policy. Systematic does not expose an mcps shortcut in V1; MCP-specific permission mapping is out of scope for this config surface.

Bundled agent markdown intentionally omits model. Instead, Systematic ships source-owned category model defaults that are emitted for bundled agents in each known category. These defaults are primary model choices only, not fallback chains. Systematic does not support fallback_models, inherited retry semantics, runtime fallback behavior, or fallback to the parent model when a source model is unavailable. Explicit and source model IDs are structurally validated and may still fail at OpenCode runtime if the provider or model is unavailable.

Overlay application precedence for a Systematic-owned bundled agent is strongest first:

1. Exact agents.<key> overlay (high-trust model wins)
2. categories.<category-id> overlay (high-trust model wins)
3. Source category model default (built-in, code-owned)
4. Bundled markdown/frontmatter defaults
5. OpenCode inherited defaults

Source category model defaults are primary model choices only — they are not fallback chains. Systematic does not support fallback_models, inherited retry semantics, runtime fallback behavior, or fallback to the parent model when a source model is unavailable. Explicit and source model IDs are structurally validated and may still fail at OpenCode runtime if the provider or model is unavailable.

If you want to restore OpenCode parent-model inheritance for a bundled agent or category (opting out of the source default), set "model": null in high-trust user or $OPENCODE_CONFIG_DIR/systematic.json config. Project config cannot use model: null — project config cannot set, erase, or shadow model at any value.

Source Category Model Defaults

The following source defaults apply to bundled Systematic agents by category when no stronger high-trust exact or category model override exists. The chain column shows the provider resolution order (first available provider/model wins); variants are shown as +variant suffixes. Run bun run docs:generate to regenerate this table from source.

Category	Chain	Rationale	When to Override
design	github-copilot/gemini-3.1-pro-preview, openai/gpt-5.5+high, anthropic/claude-opus-4-7+max, …	High-judgment UX, product, and design work benefits from a strong general reasoning model with broad creative capability.	Override to a faster/cheaper model when design tasks are primarily templating or low-stakes layout work.
docs	github-copilot/gemini-3.1-pro-preview, openai/gpt-5.4-mini, anthropic/claude-haiku-4-5, …	Documentation and summarization tasks should start cheaper and faster; quality is sufficient at mid-tier models.	—
document-review	anthropic/claude-opus-4-7+max, openai/gpt-5.5+high, github-copilot/gemini-3.1-pro-preview, …	Requirements and plan critique benefit from the strongest nuanced reasoning to surface non-obvious gaps and contradictions.	—
research	openai/gpt-5.4-mini, anthropic/claude-sonnet-4-6, github-copilot/gemini-3.1-pro-preview, …	Tool-heavy synthesis and source evaluation benefit from a strong general reasoning model with broad knowledge.	—
review	anthropic/claude-sonnet-4-6, openai/gpt-5.3-codex, github-copilot/gemini-3.1-pro-preview, …	Code, security, and adversarial review benefits from the strongest reasoning to catch subtle bugs and security issues.	Override to a faster model when review tasks are primarily style or formatting checks rather than correctness or security analysis.
workflow	openai/gpt-5.4-mini, anthropic/claude-sonnet-4-6, opencode/claude-haiku-4-5, …	Orchestration and bounded implementation tasks should default cheaper and faster; strong reasoning is rarely needed for routing decisions.	—

These defaults are owned by Systematic code and emitted only for Systematic-owned bundled agents. Uncategorized bundled agents receive no source default and continue inheriting the parent OpenCode model. Native OpenCode agents with the same emitted key are full replacements and receive no Systematic source model default.

Bundled agent markdown files must still omit model — the field belongs in source code defaults, not portable markdown. This is enforced by Systematic’s content-integrity gate.

Source defaults preserve the existing trust boundary: user config or $OPENCODE_CONFIG_DIR/systematic.json can override model per-agent or per-category, but project .opencode/systematic.json cannot set, erase, or shadow model policy.

Migration: Restoring parent-model inheritance

If you previously relied on bundled agents inheriting the parent OpenCode model (no source defaults), set "model": null in your high-trust config to opt out of the source default per agent or per category:

// ~/.config/opencode/systematic.json or $OPENCODE_CONFIG_DIR/systematic.json
{
  "categories": {
    "review": { "model": null }     // All review agents inherit parent model
  },
  "agents": {
    "security-sentinel": { "model": null }  // Single agent inherits parent model
  }
}

This only works from high-trust config (user or $OPENCODE_CONFIG_DIR/systematic.json). Project .opencode/systematic.json cannot set model: null or any model value.

Native OpenCode agents with the same emitted key are full replacements. If config.agent.security-sentinel already exists in OpenCode config, agents.security-sentinel or agents.review/security-sentinel conflicts because ownership would be ambiguous. Category overlays skip native replacements and continue applying to the remaining Systematic-owned bundled agents in that category.

Availability-Aware Resolution

Source category model defaults are provider-grouped chains rather than single strings. At plugin load, Systematic asks OpenCode which providers are connected via the plugin SDK’s client.config.providers() call, then walks each category’s provider chain in order and selects the first provider/model pair whose provider+model is in the connected set. If a connected provider has none of the category’s listed models available, resolution continues to the next provider in the chain. If no model in the chain matches, the first listed entry of the first provider is used as a last-resort fallback.

Connected providers are those OpenCode considers usable — providers with a config block in opencode.json, providers with an env var matching their provider.env list, providers with an auth.json entry of type api, or providers contributed by a plugin’s auth.loader. All four signals are merged server-side; Systematic never reads auth.json directly.

If the SDK call fails for any reason, Systematic falls back to reading the locally cached ${XDG_CACHE_HOME:-~/.cache}/opencode/models.json (or models-<hash>.json when OPENCODE_MODELS_URL is set) — the same catalog OpenCode itself writes from models.dev. A missing, unreadable, or schema-mismatched cache produces an empty availability set, which triggers last-resort resolution.

When a chain entry carries an optional variant, it flows through to the emitted agent config alongside model. User overrides via categories.<id>.variant or agents.<key>.variant win over the source variant. When an override sets model without variant, any source or lower-precedence variant is cleared so users never get a (user-model, stale-variant) hybrid.

Precedence. The availability-aware resolver applies only when no stronger user override exists. Full precedence for a bundled agent’s model:

1. agents.<key>.model (user or $OPENCODE_CONFIG_DIR/systematic.json)
2. categories.<id>.model (user or $OPENCODE_CONFIG_DIR/systematic.json)
3. Source category model default resolved against the connected-providers set
4. Bundled markdown/frontmatter defaults (unused — bundled agents omit model)
5. OpenCode inherited defaults

User-supplied agents.<key>.model and categories.<id>.model are single provider/model strings — provider-grouped chains live only in source defaults. Supplying a scalar model string skips the availability-aware resolver for that agent or category and uses your overlay as-is.

Project-Specific Content

One of Systematic’s most powerful features is the ability to add your own skills and agents that live alongside (or override) the bundled ones.

Add your content to the .opencode/ directory in your project:

.opencode/
├── skills/
│   └── my-team-workflow/
│       └── SKILL.md
├── agents/
│   └── custom-reviewer.md

Project-level commands remain supported for backward compatibility under .opencode/commands/ when you need local slash-command definitions.

Overriding Bundled Content

If you create a project-specific asset with the same name as a bundled one, yours will take precedence. This allows you to customize bundled workflows for your specific project needs without modifying the plugin itself.

Configuration Priority

Systematic resolves configuration and content in the following order (highest priority first):

1. Custom config directory: $OPENCODE_CONFIG_DIR/systematic.{json,jsonc} and assets under $OPENCODE_CONFIG_DIR/systematic/
2. Project-level assets: Files in .opencode/
3. Project-level config: .opencode/systematic.{json,jsonc}
4. User-level assets: Files in ~/.config/opencode/
5. User-level config: ~/.config/opencode/systematic.{json,jsonc}
6. Bundled assets: Content shipped with the plugin package

Config-source merge precedence is separate from overlay application precedence. Across Systematic config files, disabled_* arrays are union-merged, bootstrap is shallow-merged, and top-level agents/categories maps merge by key. A higher-priority source replaces the whole object for the same agents.<key> or categories.<id> entry; unrelated keys survive. Project overlays are the exception for trust-sensitive fields: they cannot define model, variant, permission, or skills, and same-key project overlays preserve user-level model/variant/permission/skills fields instead of erasing them. After that effective config is built, Systematic applies category and exact overlays to bundled agents using the overlay precedence above.

Advanced Configuration

The Systematic configuration file is parsed as JSONC, meaning you can include comments to document your settings.

{
  // Disable git-worktree as we use a different branching model
  "disabled_skills": ["git-worktree"],

  // Custom agents are added in .opencode/agents/; bundled agents can also be
  // tuned with overlays instead of copied.
  "disabled_agents": [],
  "categories": {
    "research": {
      "temperature": 0.2
    }
  },
  "agents": {
    "repo-research-analyst": {
      // User or custom config only; project config cannot choose model/provider routing.
      "model": "anthropic/claude-sonnet-4-5"
    }
  }
}