Configuration examples

These examples are intentionally small. Copy the pattern you need and omit the rest.

Replace placeholder model IDs such as <provider/model-strong> with model IDs exposed by your OpenCode installation.

Minimal skeleton

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

Global personalization

Good for ~/.config/opencode/squad.json:

{
  "$schema": "https://raw.githubusercontent.com/geckon/opencode-squad/main/schema/squad.schema.json",
  "primary": {
    "outputIcons": "emoji",
    "userTraits": {
      "communication": "Prefer concise answers first, with details when they affect the decision.",
      "language": "Conversation in the user's language; code, comments, and documentation in English."
    },
    "userRequirements": [
      "Challenge risky assumptions before implementation.",
      "Warn before destructive filesystem operations."
    ]
  }
}

Project rules

Good for <project>/.opencode/squad.json:

{
  "$schema": "https://raw.githubusercontent.com/geckon/opencode-squad/main/schema/squad.schema.json",
  "primary": {
    "projectRequirements": {
      "workflow": [
        "Use the package manager already used by this repository.",
        "Run the repository check command before reporting work as complete."
      ],
      "documentation": ["Write project documentation in English unless the task says otherwise."]
    }
  }
}

Simple model routing

Use one strong model pool for most work and one fast pool for discovery:

{
  "models": {
    "providers": {
      "main": ["<provider/model-strong>"],
      "fast": ["<provider/model-fast>"]
    },
    "handlers": {
      "primary": "@provider/main",
      "developer": "@provider/main",
      "coordinator": "@provider/main",
      "code_analyzer": "@provider/main",
      "scout": "@provider/fast"
    }
  }
}

Beta second opinion

Route /beta to a different model family or provider than normal primary work:

{
  "models": {
    "providers": {
      "main": ["<provider/model-primary>"],
      "second_opinion": ["<provider/model-alternative>"]
    },
    "handlers": {
      "primary": "@provider/main",
      "primary_beta": "@provider/second_opinion"
    }
  }
}

If both handlers resolve to the same concrete model, /beta is hidden because it would not provide an independent review.

Retitler with suggestions

{
  "retitler": {
    "instructions": ["Use ticket IDs when they are clearly present.", "Keep titles short, factual, and searchable."],
    "suggestions": true
  }
}

Global local paths

Only put this in global squad.json:

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

Most users should leave paths.* unset. Use these fields only when you intentionally need custom local directories.

Combining sections

A real file can combine multiple field groups:

{
  "$schema": "https://raw.githubusercontent.com/geckon/opencode-squad/main/schema/squad.schema.json",
  "primary": {
    "outputIcons": "emoji"
  },
  "retitler": {
    "suggestions": true
  },
  "models": {
    "providers": {
      "main": ["<provider/model-strong>"]
    },
    "handlers": {
      "primary": "@provider/main"
    }
  }
}

Keep combined files readable by grouping related fields and deleting empty sections.