Local paths

The paths.* fields control machine-local filesystem locations used by stateful plugin features and container helpers.

They are trusted fields. The runtime honors them only from global squad.json; project config and plugin tuple options are ignored for these fields.

Why paths are global only

A repository should not be able to redirect your local plugin state or container definitions to attacker-chosen paths. Keeping paths.* global means these overrides come from your machine-level configuration, not from a project checkout.

Data directory

paths.dataDir controls where stateful tools store plugin-managed data such as scratchpads, handoffs, and review context.

{
  "paths": {
    "dataDir": "/absolute/path/to/opencode-squad-data"
  }
}

Runtime priority:

1. $OPENCODE_DATA_DIR environment variable.
2. paths.dataDir from global squad.json.
3. OpenCode config directory data folder.

Prefer the environment variable for temporary experiments. Use paths.dataDir when you want a persistent machine-level setting.

Container asset directory

paths.containersDir points to custom container helper definitions:

{
  "paths": {
    "containersDir": "/absolute/path/to/opencode-squad-containers"
  }
}

Most users should leave this unset. Set it only when you intentionally maintain custom container assets outside the package’s bundled definitions.

Rules

• Put paths.* only in global squad.json.
• Use absolute paths.
• Do not rely on ~ or shell variable expansion inside JSON strings.
• Confirm the directories exist and are writable before using them.
• Do not put secrets in these paths just because they are local.