Configuration

Systematic works out of the box with sensible defaults. This page covers every way to customize its behavior.

Config File Locations

Systematic looks for configuration in three places, checked in this order (highest priority first):

Custom config directory: $OPENCODE_CONFIG_DIR/systematic.{json,jsonc}
Project-specific: .opencode/systematic.{json,jsonc}
Global: ~/.config/opencode/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 the existing file.

Common Examples

Disabling bundled content

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

Tuning agents by category

{
  "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
    }
  }
}

Tuning a specific agent

{
  "agents": {
    "security-reviewer": {
      // User or custom config only; project config cannot choose model/provider routing.
      "model": "anthropic/claude-sonnet-4-5",
      "variant": "thinking",
      "temperature": 0.2,
      "steps": 30
    }
  }
}

Trust Boundaries

Fields that control provider routing or capability policy — model, variant, permission, and skills — are accepted only from user config (~/.config/opencode/systematic.json) or $OPENCODE_CONFIG_DIR/systematic.json. Project config may tune non-sensitive fields such as temperature, top_p, mode, color, steps, hidden, or exact-agent disable, but it cannot choose model/provider routing or loosen permission/capability policy.

A typo in agents.<key>, disabled_agents, or disabled_skills fails loudly with a clear error that names the offending key — no silent misconfiguration.

Workflow Guard

The workflow guard records privacy-safe receipts for supported engineering operations and surfaces whether guarded workflow requirements are satisfied. It covers local implementation and verification work, commits, pushes, and GitHub pull-request, check, and review readback when the required Git and GitHub environment is available.

The guard ships in observe mode by default. It records and reports workflow state without blocking operations. Protected mode is opt-in; it can reject a guarded transition when required evidence is missing or stale. Disabled mode turns the guard off for the configured scope.

{
  "workflow_guard": {
    "mode": "observe",
    "debug": false
  }
}

workflow_guard is trust-protected. Set it in user configuration (~/.config/opencode/systematic.json) or $OPENCODE_CONFIG_DIR/systematic.json; project-level .opencode/systematic.json cannot set this field.

Agent and Category Overlays

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

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

Exact agents.<key> overlay (high-trust model wins)
categories.<category-id> overlay (high-trust model wins)
Bundled markdown/frontmatter defaults (model-free)
OpenCode inherited defaults

Bundled agents inherit the invoking model unless high-trust user or $OPENCODE_CONFIG_DIR/systematic.json config supplies an explicit model. Set "model": null to clear an explicit model and restore parent-model inheritance. Project config cannot set, erase, or shadow model at any value.

Schema and Autocomplete

Add a $schema field to your systematic.json to enable per-key autocomplete in editors that honor JSON Schema property completion:

{
  "$schema": "https://fro.bot/systematic/schemas/v3/systematic-config.schema.json",

  "disabled_skills": ["git-worktree"],
  "agents": {
    "correctness-reviewer": { "temperature": 0.1 },
    "security-reviewer": { "steps": 20 }
  }
}

VS Code is the reference target — it picks up $schema automatically and provides inline completion, hover documentation, and validation squiggles. Zed, IntelliJ, and other editors that support JSON Schema property completion will also benefit, though support varies by editor version.

Typed Validation

Since v2.15.0, Systematic validates agents.<key>, disabled_agents, and disabled_skills against the actual set of bundled names at load time. A typo fails loudly with a clear error that names the offending key. The valid bundled names are listed in the error when validation fails, so the error message is the fix.

If your config contains a typo in any of these fields, Systematic will fail to load on upgrade and surface the error. The fix is to correct the key to a valid bundled name.

Field Reference

The sections below are auto-generated from src/lib/config-schema.ts. Do NOT edit the content between the SYSTEMATIC:FIELD-REFERENCE markers — run bun run docs:generate to regenerate.

Agent/Category Overlay Fields

The agents and categories sections share the same set of per-entry overlay fields. Each key under agents or categories is an object with the following fields. (The disable field is only valid under agents, not categories.)

model

Model identifier in provider/model format, or null to inherit parent model

Type: string | null

Examples:

anthropic/claude-sonnet-4

null

variant

Model variant identifier

Type: string

Examples:

v2

extended

temperature

Sampling temperature (≥0; 0 = deterministic)

Type: number

Examples:

0.1

0.7

top_p

Nucleus sampling parameter (0 to 1)

Type: number

Examples:

0.9

0.1

mode

Agent execution mode

Type: string

Valid values: subagent, primary, all

Examples:

subagent

primary

all

color

Agent color — named token from OpenCode or 6-digit hex color (#RRGGBB)

Type: string | string

Examples:

primary

#ff6600

steps

Maximum execution steps (positive integer)

Type: integer

Examples:

hidden

Hide agent from UI

Type: boolean

Examples:

true

false

disable

Disable this agent overlay

Type: boolean

Examples:

true

false

skills

Skills enabled for this agent

Type: string[]

Examples:

[
  "ce:plan",
  "ce:review"
]

permission

Permission overrides per tool

Type: object

Examples:

{
  "edit": "allow",
  "bash": {
    "curl": "allow",
    "rm": "deny"
  }
}

$schema

JSON Schema URL for IDE autocomplete. The value is informational only — the loader does not fetch or validate against it. Add this to enable IDE schema activation and field-level autocomplete in editors that support JSON Schema (VSCode, Zed, IntelliJ).

Type: string

Examples:

"$schema": "https://fro.bot/systematic/schemas/v3/systematic-config.schema.json"

agents

Per-agent configuration overlays keyed by bundled agent name (bare or qualified category/name). Unknown keys are rejected with a Zod parse error. To overlay a user-defined agent, configure it through OpenCode-native config (.opencode/opencode.json) instead.

Type: object Default: {} Examples:

{
  "correctness-reviewer": {
    "temperature": 0.1
  }
}

{
  "review/correctness-reviewer": {
    "temperature": 0.1
  }
}

{}

Per-entry overlay fields are documented in the Agent/Category Overlay Fields section above.

disabled_skills

Array of bundled skill names to disable globally. Unknown skill names are rejected at parse time.

Type: string[] Default: [] Examples:

[
  "ce:plan",
  "ce:review"
]

disabled_agents

Array of bundled agent names (bare or qualified category/name) to disable globally. Unknown agent names are rejected at parse time.

Type: string[] Default: [] Examples:

[
  "previous-comments-reviewer",
  "cli-readiness-reviewer"
]

[
  "review/security-reviewer"
]

disabled_commands

Array of command names to disable globally

Type: string[] Default: [] Examples:

[
  "deprecated-migration-helper"
]

bootstrap

Bootstrap prompt configuration

Type: object Default: {"enabled":true} Examples:

{
  "enabled": true
}

{
  "enabled": false,
  "file": ".opencode/custom-prompt.md"
}

enabled

Enable bootstrap prompt injection into every conversation

Type: boolean Default: true

Examples:

true

false

file

Path to a custom bootstrap prompt file

Type: string

Examples:

~/.config/opencode/bootstrap.md

workflow_guard

Workflow guard configuration

Type: object Default: {"mode":"observe","debug":false} Examples:

{
  "mode": "observe",
  "debug": false
}

pi_subagents

Pi-native pi-subagents export field overlays (thinking, max_turns, tools, skills). Category values apply first; per-agent values override. No model field — model stays in the categories/agents overlay.

Type: object Default: {"categories":{},"agents":{}} Examples:

{
  "categories": {
    "research": {
      "thinking": "high"
    }
  },
  "agents": {
    "repo-research-analyst": {
      "max_turns": 10
    }
  }
}

agents

Per-agent pi-subagents export overlays keyed by bundled agent name

Type: object Default: {}

Examples:

{
  "repo-research-analyst": {
    "max_turns": 10
  }
}

{}

Per-entry overlay fields are documented in the Pi-subagents Overlay Fields section below.

skills_as_commands

Register skills discovered from user/project skill directories (OpenCode config and other agent-harness-standard locations) as slash commands. Default true.

Type: boolean Default: true Examples:

true

false

Pi-subagents Overlay Fields

The pi_subagents.categories and pi_subagents.agents sections share the same set of per-entry overlay fields. Each key under pi_subagents.categories or pi_subagents.agents is an object with the following fields.

thinking

pi-subagents reasoning effort level for exported persona frontmatter

Type: string

Valid values: off, minimal, low, medium, high, xhigh, max

Examples:

off

medium

high

max_turns

pi-subagents maximum turns for a delegated persona (0 = unlimited)

Type: integer

Examples:

tools

pi-subagents comma-selector tool string (built-ins, */all/none, or extension selectors)

Type: string

Examples:

read,grep,glob

none

skills

pi-subagents skills selector: true (all) or a comma-separated list of skill names

Type: boolean | string

Examples:

true

ce:plan,ce:review

Offline IDE behavior

The schema’s $id points to the canonical online URL above, so IDEs that prefer fetching the canonical schema may attempt to reach the docs site even when the bundled npm copy is also on disk. If you need strict offline behavior, configure your editor to associate systematic.{json,jsonc} with node_modules/@fro.bot/systematic/dist/schemas/systematic-config.schema.json directly.