Model Selection

hatch3r lets you configure preferred AI models for your agents. You can set a global default, override per agent, or use project-specific customization files.

Overview

When you configure a model, hatch3r includes it in the generated config for each tool (Claude Code, Cursor, Copilot). Some platforms support native model selection in their config; others receive the recommendation as guidance text. Either way, the preference is preserved across npx hatch3r sync runs.

When no model is configured at any level, hatch3r does not emit a model preference. Each platform uses its own default.

Configuration Points

Source	Path	Precedence
Customization YAML	.hatch3r/agents/{agent-id}.customize.yaml	Highest
Manifest per-agent	hatch.json -> models.agents.{agent-id}	2nd
Canonical agent	agents/{agent-id}.md frontmatter model: (bundled content; override under .hatch3r/overrides/agents/)	3rd
Manifest default	hatch.json -> models.default	4th
(none)	--	Platform auto-select

Resolution Order

1. Customization file -- .hatch3r/agents/{agent-id}.customize.yaml with a model field wins
2. Manifest per-agent -- hatch.json -> models.agents[agent-id]
3. Canonical agent frontmatter -- model: in the bundled agents/{agent-id}.md (or its .hatch3r/overrides/agents/ override)
4. Manifest default -- hatch.json -> models.default
5. No model -- platform uses its own default

Aliases

Use short aliases instead of full model IDs. hatch3r resolves them before emitting.

Alias	Resolves To
opus	claude-opus-4-6
sonnet	claude-sonnet-4-6
haiku	claude-haiku-4-5
codex	gpt-5.3-codex
codex-prev	gpt-5.2-codex
codex-mini	gpt-5.1-codex-mini
codex-spark	gpt-5.3-codex-spark
gemini-pro	gemini-3.1-pro
gemini-flash	gemini-3-flash
gemini-stable	gemini-2.5-pro

Unknown values are passed through as-is.

Examples

hatch.json

{
  "models": {
    "default": "opus",
    "agents": {
      "hatch3r-lint-fixer": "sonnet",
      "hatch3r-testability": "gemini-pro"
    }
  }
}

Canonical agent frontmatter

In the canonical agents/hatch3r-implementer.md (bundled content):

---
id: hatch3r-implementer
description: Focused implementation agent for a single issue.
model: opus
---

Customization YAML

In .hatch3r/agents/hatch3r-reviewer.customize.yaml (keyed by id via its filename, so set only override fields):

model: codex

Built-in Agent Defaults

Some agents ship with a default model in their canonical frontmatter. These defaults are tuned for the agent's cognitive profile.

Agent	Default	Rationale
hatch3r-lint-fixer	haiku	Mechanical pattern fixes; speed and low cost
hatch3r-ci-watcher	haiku	Log parsing and pattern recognition; fast feedback
hatch3r-docs-writer	sonnet	Writing quality and technical accuracy
hatch3r-security	sonnet	OAuth/OIDC/supply-chain analysis
hatch3r-ui	sonnet	WCAG 2.2 AA + design-token interpretation
hatch3r-testability	sonnet	Edge-case identification and test design

Agents without a default (hatch3r-implementer, hatch3r-researcher, hatch3r-reviewer, hatch3r-performance) use the platform's own default.

Override at any higher precedence level:

{
  "models": {
    "agents": {
      "hatch3r-lint-fixer": "sonnet"
    }
  }
}

Cross-Platform Override

Built-in defaults resolve to Anthropic model IDs. Cursor and Copilot can also drive non-Anthropic providers (e.g. OpenAI GPT models) — to run hatch3r agents on those, set a project-wide override:

{
  "models": {
    "default": "codex",
    "agents": {
      "hatch3r-lint-fixer": "codex-spark",
      "hatch3r-ci-watcher": "codex-spark"
    }
  }
}

Platform Behavior

Platform	Native config?	When model is set
Cursor	Yes	model: in agent YAML frontmatter
Copilot	Yes (VS Code)	model: in agent YAML; ignored on github.com
Claude Code	No	Guidance: /model command and env var

• Native config -- the tool can apply the model directly
• Guidance -- the model is included as instructional text; users set it manually