Configuration overview

opencode-squad is configured with a strict JSON file named squad.json. You can keep the plugin almost configuration-free, or you can gradually add personal preferences, project rules, model routing, session-title behavior, and machine-local paths.

Start small. Add only the field group you actually need, then grow the file when the workflow asks for it.

Configuration sources

Configuration can come from three user-controlled places:

Source	Typical use
Global `squad.json`	Personal preferences, model inventory, user-wide requirements, and trusted local paths.
Project `.opencode/squad.json`	Repository conventions and project-specific routing.
Plugin tuple options	One OpenCode config file that needs a local override while registering the plugin.

See Locations and precedence for exact paths, merge order, and trust boundaries.

Minimal valid file

A new file can start with only a schema reference:

{
  "$schema": "https://raw.githubusercontent.com/geckon/opencode-squad/main/schema/squad.schema.json"
}

The $schema field is optional at runtime, but useful in editors because it enables validation and completions.

Supported field groups

Area	Page	What it controls
`primary.*`	Primary agents	Primary-agent identity, persona, output style, user traits, and requirements.
`models.*`	Model routing	Provider pools, workload handlers, per-agent overrides, fallback, and availability selection.
`retitler.*`	Retitler	Persistent behavior for the `/retitler` session-title command.
`paths.*`	Local paths	Trusted machine-local directories for data and container assets.

For copyable starting points, see Configuration examples.

Practical rules

Put personal preferences in global squad.json.
Put repository conventions in project .opencode/squad.json.
Keep paths.* global only; project files and tuple options cannot safely control machine-local paths.
Omit models.* unless you want explicit model routing. Without it, OpenCode’s current/default model can still be used.
Prefer provider pools and handlers before per-agent model overrides.

Example: small project config

This project-level file adds only repository rules:

{
  "primary": {
    "projectRequirements": [
      "Use the package manager already used by this repository.",
      "Run the project check command before claiming completion."
    ]
  }
}

The rest of this section breaks the configuration surface into separate pages so each area can grow without turning the overview into a reference dump.

On this page