Locations and precedence

opencode-squad merges configuration from defaults, files, and optional plugin tuple options. Later sources override earlier sources, except for fields that are intentionally limited to trusted global configuration.

Global config

Global configuration belongs to the user and the current machine:

$OPENCODE_CONFIG_DIR/squad.json

When $OPENCODE_CONFIG_DIR is unset, OpenCode’s normal config directory is used:

~/.config/opencode/squad.json

Use the global file for personal preferences, user-wide behavior rules, model inventory, model selection strategy, and trusted local paths.

Project config

Project configuration lives in the repository:

<project>/.opencode/squad.json

Use project config for repository conventions, project-specific requirements, and project-specific model routing. Do not use it for secrets or machine-local path overrides.

Plugin tuple options

OpenCode lets a plugin registration pass inline options. This can be useful when one OpenCode configuration file needs a local override at plugin load time:

{
  "plugin": [
    [
      "opencode-squad",
      {
        "models": {
          "handlers": {
            "primary": "@provider/main"
          }
        }
      }
    ]
  ]
}

Prefer squad.json for settings that should be reused across sessions or shared with a project. Tuple options are best for narrow local experiments.

Merge order

The runtime merges configuration in this order:

Built-in defaults.
Global squad.json, when present.
Project .opencode/squad.json, when present.
Plugin tuple options, when present.

Later sources override earlier sources. For example, a project can override a global model handler for that repository, and tuple options can override both for one plugin registration.

Trusted-source exceptions

Some fields are accepted only from specific sources:

Field	Accepted from	Why
`primary.userRequirements`	Global config	User-wide rules should be controlled by the user, not by a repository.
`primary.projectRequirements`	Project config	Repository rules should stay attached to the repository.
`paths.dataDir`	Global config	A project must not redirect local plugin state.
`paths.containersDir`	Global config	A project must not redirect container helper definitions.

When a source tries to set a field outside its trust boundary, the runtime ignores that value and reports a diagnostic instead of silently applying it.

Invalid or unsupported config

squad.json is strict JSON: no comments and no trailing commas. If a config file cannot be read, parsed, or validated, the plugin reports the diagnostic and continues with the remaining valid sources.

On this page