msd-core/docs/how-to/configure-model-profiles.md

How to configure model profiles

Choose the right model tier strategy for your project, then tune individual agents or entire phase types without writing a large override block. This guide starts with the simplest lever and works up to dynamic routing.

---

The four profiles (plus adaptive and inherit)

Set model_profile in .planning/config.json or via /gsd-config --profile <name>:

Profile	Planner	Executor	Researchers	Verifier	Use when
quality	Opus	Opus	Opus	Sonnet	Production-quality work where cost is secondary
balanced	Opus	Sonnet	Sonnet	Sonnet	Normal development — the default
budget	Sonnet	Sonnet	Haiku	Haiku	Rapid prototyping, cost-sensitive contexts
adaptive	Opus	Sonnet	Sonnet	Sonnet	Resolves the same way as the other tiers under runtime-aware profiles; use when switching between runtimes frequently
inherit	(session model)	(session model)	(session model)	(session model)	Non-Anthropic providers (OpenRouter, local models) — all agents follow your current session model

The table above shows a representative subset. All 33 shipped agents have explicit per-profile tier assignments in sdk/shared/model-catalog.json. For the full table see Model Profiles in the configuration reference.

Quick switch via command:

/gsd-config --profile balanced   # Normal development
/gsd-config --profile budget     # Prototyping or high-cost phases
/gsd-config --profile quality    # Production release
/gsd-config --profile inherit    # OpenRouter, local models

Or edit .planning/config.json directly:

{
  "model_profile": "balanced"
}

---

Per-agent overrides (model_overrides)

If a single agent needs a different tier without changing the whole profile, use model_overrides:

{
  "model_profile": "balanced",
  "model_overrides": {
    "gsd-executor": "opus",
    "gsd-codebase-mapper": "haiku"
  }
}

Valid values: opus, sonnet, haiku, inherit, or any fully-qualified model ID (e.g. "openai/o3", "google/gemini-2.5-pro").

model_overrides can be set per-project in .planning/config.json or globally in ~/.gsd/defaults.json. Per-project entries win on conflict; non-conflicting global entries are preserved.

Important for Codex and OpenCode: Those runtimes embed the model into each agent's static config at install time rather than choosing it per spawn, so after editing model_overrides you must re-run the installer for the change to take effect:

npx @opengsd/gsd-core@latest --codex --global   # or --opencode, --kilo, etc.

GSD will also warn you if you forget: workflow entry commands (gsd init plan-phase, gsd init execute-phase, etc.) detect when .planning/config.json or ~/.gsd/defaults.json is newer than your installed agent files and print a one-line stderr reminder naming the changed file and the re-install command. The check is read-only and runs only on codex and opencode; Claude Code resolves models at spawn time and is unaffected. (#1688)

---

Per-phase-type models (models)

If you want to say "Opus for planning, Sonnet for everything else" without learning all 33 agent names, use the models block. It maps six phase types to tier aliases:

{
  "model_profile": "balanced",
  "models": {
    "planning":      "opus",
    "discuss":       "opus",
    "research":      "sonnet",
    "execution":     "opus",
    "verification":  "sonnet",
    "completion":    "sonnet"
  }
}

Phase types and their agents:

Phase type	Agents covered
planning	gsd-planner, gsd-roadmapper, gsd-pattern-mapper
research	gsd-phase-researcher, gsd-project-researcher, gsd-research-synthesizer, gsd-codebase-mapper, gsd-ui-researcher
execution	gsd-executor, gsd-debugger, gsd-doc-writer
verification	gsd-verifier, gsd-plan-checker, gsd-integration-checker, gsd-nyquist-auditor, gsd-ui-checker, gsd-ui-auditor, gsd-doc-verifier, gsd-code-reviewer
discuss	gsd-assumptions-analyzer
completion	Reserved — no subagent today; accepted by schema for forward compatibility

The models block accepts tier aliases only (opus, sonnet, haiku, inherit). For a fully-qualified model ID, use model_overrides per agent instead.

Combining models with a per-agent exception:

{
  "model_profile": "balanced",
  "models": {
    "research": "sonnet"
  },
  "model_overrides": {
    "gsd-codebase-mapper": "haiku"
  }
}

All five research agents resolve to sonnet except gsd-codebase-mapper, which is pinned to haiku.

---

Dynamic routing — start cheap, escalate on failure

If you want to pay for cheaper tiers by default and only escalate when an agent fails a quality gate, enable dynamic_routing:

{
  "dynamic_routing": {
    "enabled": true,
    "tier_models": {
      "light":    "haiku",
      "standard": "sonnet",
      "heavy":    "opus"
    },
    "escalate_on_failure": true,
    "max_escalations": 1
  }
}

Each agent has a default tier (light, standard, or heavy). On the first attempt, GSD picks tier_models[default_tier]. If the orchestrator detects a soft failure (verification inconclusive, plan-check flagged, etc.), it re-spawns the agent one tier up. max_escalations caps the total retries.

Agents that already sit at heavy cannot escalate further.

Turning off escalation while keeping dynamic resolution:

{
  "dynamic_routing": {
    "enabled": true,
    "escalate_on_failure": false
  }
}

Every attempt uses tier_models[default_tier] regardless of outcome — useful when you want explicit tier-to-model mapping without the escalation behaviour.

dynamic_routing is disabled by default. Omitting the block or setting enabled: false preserves static resolution.

Keep going when a provider throttles you

The tier ladder above escalates within one provider. When the provider itself is the thing that ran out of quota, a heavier tier on the same account is still throttled. Add provider_escalation — an ordered list of fallback model IDs — to keep the phase moving instead of stopping for a manual restart:

{
  "dynamic_routing": {
    "enabled": true,
    "tier_models": { "light": "haiku", "standard": "sonnet", "heavy": "opus" },
    "provider_escalation": ["gpt-5", "nvidia/llama-3.3"],
    "max_escalations": 2
  }
}

When an executor dies on a rate limit, GSD classifies the error body, switches to the next model in the list, logs the swap (sonnet → gpt-5), and waits out any Retry-After the provider sent. The walk is capped at min(max_escalations, provider_escalation.length). Once the list is spent, GSD names every model it tried and hands you the normal recovery prompt — it never silently retries the exhausted one.

This is most useful on providers without a guaranteed SLA (Nvidia NIM, OpenRouter, and other third-party OpenCode models), where a throttle mid-phase is routine. It only fires on quota / rate-limit failures; other failures keep the tier ladder. Leaving provider_escalation unset preserves the manual wait-for-reset behaviour exactly.

---

Using GSD on non-Anthropic runtimes

If you installed GSD for Codex, OpenCode, Antigravity CLI, or Kilo, the installer already set resolve_model_ids: "omit" in your config. This tells GSD to skip Anthropic model ID resolution and let the runtime choose its own default model. No manual setup is needed for the basic case.

Codex does not do tier routing — pin explicitly instead

Codex agents inherit whatever model your Codex session is using. GSD writes no model line into ~/.codex/agents/<agent>.toml, so setting model_profile has no effect on Codex.

This is deliberate (ADR-2313). A ChatGPT-account Codex session exposes only its own model, so a pinned tier model fails the request outright — 400 invalid_request_error: "The 'sonnet' model is not supported when using Codex with a ChatGPT account" — and the agent never spawns.

To pin a model on Codex, name a real Codex model id per agent:

{
  "runtime": "codex",
  "model_overrides": {
    "gsd-planner":  "gpt-5.6-sol",
    "gsd-executor": "gpt-5.6-terra"
  }
}

Then re-run the installer, as with any model_overrides edit on Codex (see above).

Two rules apply to what you can put there:

• It must be a real Codex model id. A GSD tier alias (opus, sonnet, haiku, fable) or a claude-* id is dropped with a warning rather than written, because Codex rejects them.
• Your account must actually expose it. GSD cannot check this — if you pin gpt-5.6-sol on an account that does not have it, you get the same 400. When in doubt, omit the pin and let the session model apply.

model_reasoning_effort follows the model: with no pin, GSD writes no effort line either, so the Codex UI drives both rather than one following GSD and the other following your session.

Upgrading from v1.10 or earlier? Codex installs used to embed a per-tier model (opus→gpt-5.6-sol, sonnet→gpt-5.6-terra, haiku→gpt-5.6-luna). If you were on an API-key account where those resolved successfully, add the model_overrides block above to keep them. The installer prints a one-time notice when it drops a pin. If you were on a ChatGPT account, this is the change that stops the 400s — nothing to do.

If you want per-agent model IDs on any non-Claude runtime:

{
  "resolve_model_ids": "omit",
  "model_overrides": {
    "gsd-planner":   "o3",
    "gsd-executor":  "o4-mini",
    "gsd-debugger":  "o3"
  }
}

For the full runtime-aware profiles reference and the model_policy surface (provider-neutral presets added in v1.42), see Configuration reference — Model Profiles.

---

Resolution precedence (highest to lowest)

When multiple layers apply, the resolver picks the highest-priority entry:

1. model_overrides[<agent>]           — per-agent; full IDs; targeted exception
2. dynamic_routing.tier_models[<tier>] — when enabled; escalates on soft failure
3. models[<phase_type>]               — coarse phase-level tier
4. model_profile (per-agent column)   — global tier strategy
5. Runtime default                    — when nothing else applies

---

Choosing the right lever

You want	Use
One tier strategy for all agents	model_profile
Coarse phase-level tuning ("Opus for planning")	models.<phase_type>
Per-agent precision ("force Haiku on the codebase mapper")	model_overrides[<agent>]
A fully-qualified model ID for a specific agent	model_overrides[<agent>]: "openai/gpt-5"
Start cheap, escalate only on failure	dynamic_routing
All agents follow the session model (non-Anthropic provider)	model_profile: "inherit"

---

Related

• Configuration reference
• Multi-agent orchestration
• Commands reference
• Docs index