Model Forge

Model Forge

Routing reference for picking the right model and the right git strategy. Consult before any subagent dispatch or non-trivial change.

Critical Rule

ALWAYS run subagents in background (run_in_background: true) UNLESS the user explicitly asks for foreground. The main thread stays unblocked, the user can keep working, and long-running dispatches don't freeze the conversation. Foreground subagents are the exception, not the default.

Model Capability Matrix

claude-opus-4-6

Heaviest reasoning, best at multi-file architecture and critical correctness. Slowest and most expensive claude. Speed/cost: ~3-5x slower than sonnet, ~5x cost premium. Use for:

• Deep architecture design and hard refactors
• Security audits requiring full mental model
• Complex math, proofs, algorithmic correctness
• Novel problems with no clear path
• Multi-system integration design
• Critical decisions where being wrong is expensive

claude-sonnet-4-6

Balanced workhorse. Default for ~90% of work and most subagent dispatches. Speed/cost: solid throughput, mid-tier cost. Use for:

• Standard feature coding and debugging
• Research synthesis and writing
• Code review for logic and readability
• Scaffolding new modules from spec
• Most multi-step subagent tasks
• Anything you'd default to without thinking

claude-haiku-4-5

Fastest and cheapest. Capable enough for mechanical work. Speed/cost: near-instant, fraction of sonnet cost. Use for:

• File reads, scans, classification
• Transcription (youtube, audio, OCR)
• Single tool calls with no reasoning
• Grep-style searches across large trees
• Generating structured metadata from raw input
• Bulk context gathering across many files

gpt-5.4 (via codex plugin)

Adversarial engineer with different priors than claude. Mechanically excellent on focused tasks, brittle on vague ones. Extremely slow. Speed/cost: ~30x slower than sonnet (10 min vs 18s in real tests). 3-4x fewer tokens than claude on comparable work. ChatGPT Plus = 30-150 msgs/5hr window. Benchmarks: terminal-bench 77.3% vs claude 65.4%. Debate mode (claude + codex) bug detection jumps 53% → 80%. IMPORTANT: Always pass --model gpt-5.4 (or model: "gpt-5.4" in subagent config). Default model selection is unreliable - lock it explicitly every time. Use for:

• Adversarial code review (highest-ROI use case - independent priors catch what claude misses)
• Focused bug fixes with a clear spec and acceptance criteria
• Mechanical refactors to a defined pattern (85-90% success on bounded scope)
• Test coverage for existing logic (stays in lane, no scope creep)
• Maintenance batch work (deps, doc fixes, webhook changes - queue 3-5 at session start)
• Terminal/CLI workflows
• Second-opinion on completed code

Routing Decision Tree

1. Is the task trivial / single tool call / scan / transcription / classification? → haiku
2. Standard coding / research / writing / debugging / scaffolding? → sonnet (default)
3. Deep architecture / hard multi-file refactor / correctness-critical / novel? → opus
4. Adversarial bug hunt / security audit / can wait 10+ min? → codex (background only)
5. Time-sensitive (need result test -> fix)

• Round-trip overhead exceeds task duration
• You need the tool results in your own context

Always:

• Run subagents in background (run_in_background: true) so the main thread stays unblocked
• Lock codex model explicitly to gpt-5.4 on every invocation
• Send parallel dispatches in a single message, not sequential calls

Never:

• Run parallel agents on the same files without worktrees
• Dispatch codex for anything you're watching live
• Use opus for trivial tool calls
• Run subagents in foreground when background works

Git Strategy

Direct on current branch

• Change is `)
• Diff is large enough to bundle commits
• Single linear workstream, no overlapping agents
• Want to test/review before merging
• Example: git checkout -b feat/auth-refresh for new auth flow

Git worktree

• Multiple subagents touching overlapping files
• Want experiment isolation while main work continues
• Long-running opus/codex shouldn't dirty working tree
• Example:

``bash git worktree add ../project-feat-api feat/api-layer # dispatch sonnet into ../project-feat-api # main agent stays unblocked in original tree git merge feat/api-layer git worktree remove ../project-feat-api ``

Quick Reference

| task type | model | branch | parallel? | background? | |---|---|---|---|---| | transcription / extraction | haiku | current | yes | yes | | file scan / grep | haiku | current | yes | no | | bulk context gathering | haiku | current | yes | yes | | research synthesis | sonnet | current | yes | optional | | code review (logic/style) | sonnet | current | no | no | | scaffolding new module | sonnet | feat | no | no | | writing docs | sonnet | feat | no | no | | debugging (interactive) | sonnet | current | no | no | | large refactor | opus | worktree | no | yes | | novel architecture | opus | feat | no | no | | security design | opus | feat | no | no | | adversarial code review | codex | feat | no | yes | | bug hunt | codex | worktree | no | yes | | security audit | codex | feat | no | yes |

Codex-Specific Failure Modes

Codex is too literal. It will fulfill the exact request and break adjacent things. Real example from HN: asked to "fix compiler warnings", it made a bunch of values nullable to silence the warnings - technically correct, broke data integrity downstream.

Codex will fail at (NEVER use it for):

• UI work of any kind - layouts, components, styling, UX, design judgment. Codex has zero taste and no eye for visual hierarchy. Always claude.
• Anything you need to discuss - "yo i need to talk about this", brainstorming, exploration, "what do you think", trade-off conversations. Codex is a one-shot executor, not a collaborator. Always claude.
• Reading user intent - "make it better" → won't make leaps, will pick the most literal interpretation
• Architecture/product judgment - no sense of tradeoffs beyond what's written
• Obscure libraries - hallucinates rather than admitting unknown
• Multi-file dependency chains - gets stuck in circles
• Continuous conversation context - context degrades fast, not built for back-and-forth

Codex will excel at:

• Tasks where being literal is a feature (test writing, mechanical refactors)
• Clearly-bounded specs with acceptance criteria
• Adversarial passes with explicit focus arguments

Prompt requirements for codex:

• One concern per prompt (don't bundle)
• Explicit scope boundaries (which files, what behavior, what done looks like)
• Structured sections: General → Autonomy → Code Implementation → Editing Constraints → Exploration → Plan Tool
• Use the positional focus argument: /codex:adversarial-review challenge whether this caching design was right
• Heavy XML structure beats prose for multi-step specs

Optimal Codex Workflow

The pattern that works (claude + codex hybrid):

1. Claude builds - architecture, exploration, back-and-forth iteration
2. Codex reviews - dispatch /codex:adversarial-review with a specific focus after a major change. 6-10 min wait, actionable findings
3. Claude filters - triage codex output: "which are real issues vs noise, which need design decisions"
4. Codex fixes - confirmed bugs with clear specs get delegated back to codex
5. Batch maintenance - queue codex with 3-5 P2 tasks at session start, work on real stuff while it churns

What doesn't work:

• Letting codex drive architecture decisions
• Vague task descriptions
• Auto-running codex on every claude response (drains usage fast)

Anti-patterns

1. Codex for time-sensitive work - 10+ min latency kills interactive flow
2. Codex with vague prompts - it will interpret literally and break things
3. Opus for trivial tool calls - haiku does it at 5% cost
4. Worktrees for non-overlapping single-agent work - merge overhead with no upside
5. Big refactors on main - hard rollback, polluted history
6. Parallel agents on same files without worktrees - concurrent write conflicts
7. Dispatching codex synchronously - always background, never wait
8. Forgetting --model gpt-5.4 - default selection is unreliable
9. Codex for UI work - zero taste, no visual judgment, will produce bricks
10. Codex when you need to discuss/brainstorm - it's a one-shot executor, not a collaborator

Examples

Bulk context gathering: 5 independent file reads → 5 haiku in parallel, single message dispatch.

New feature scaffolding (small): sonnet, current branch, no subagents.

New feature scaffolding (big, multi-file): sonnet, feat/ branch, optional sonnet subagents for independent modules.

Security audit before launch: codex in background on feat/audit worktree, you keep building on main.

Hard refactor across 20 files: opus in worktree, you stay on main fixing other stuff, merge when done.

"Find all references to X across the codebase": haiku, current branch, no subagent (Grep tool is faster).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: alxxpersonal
• Source: alxxpersonal/forge
• License: MIT

Install and usage instructions live in the source repository linked above.