README

Claude Code model strategy & subagents

This repo configures Claude Code in two layers. The split between "plan on Opus, build on Sonnet" is a session-model concern, not a subagent concern — so it lives in settings.json, and the subagents below cover the other activities where a different model genuinely helps.

Layer 1 — session model (.claude/settings.json)

{ "model": "opusplan" }

opusplan runs Opus while in Plan mode and Sonnet for normal interaction and implementation. That is the entire "planning → Opus, coding → Sonnet" requirement, done at the level that actually controls it.

Why not do this with a subagent? A subagent's model: field only governs work that Claude delegates to that subagent. It does not govern Plan mode or the main implementation loop — those run on the session model. So no .claude/agents/*.md setting can make "planning use Opus while coding uses Sonnet"; opusplan is the correct mechanism.

Caveats (read these)

• Opus access required. opusplan needs Opus entitlement (Claude Max, or API/Enterprise). On the Pro plan Opus is unavailable and this setting won't engage.
• This is a checked-in default, not a lock. Project settings.json overrides a collaborator's ~/.claude/settings.json model, but a per-session /model (or --model / ANTHROPIC_MODEL) still wins. Anyone who can't use Opus can override with /model sonnet. To make it personal instead of shared, move the model key into .claude/settings.local.json (gitignored).
• Env vars silently win. Session model precedence is roughly /model > --model > ANTHROPIC_MODEL env > settings file. Subagent model precedence is CLAUDE_CODE_SUBAGENT_MODEL env > per-invocation > frontmatter > main model. If you export ANTHROPIC_MODEL or CLAUDE_CODE_SUBAGENT_MODEL anywhere in your shell profile, it overrides everything here.
• No 1M context in the plan phase. The automatic 1M-context upgrade applies to the plain opus setting, not opusplan — the plan-mode Opus phase uses the standard context window. For planning against very large contexts, prefer a manual /model opus session.
• Aliases vs pinned IDs. The agents below use aliases (opus, sonnet, haiku). To pin versions, swap an alias for a full ID (claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5-20251001). opusplan itself cannot be pinned — pinning means managing the plan/code split manually.