Models and CLIs
Everywhere forge takes a model, it takes the same short name: alias:effort:harness. Only the alias is required. That's how one command can build with GPT on Codex and review with Claude on Claude Code.
Reading a model name
| You write | forge runs |
|---|---|
sol | sol at the role's default effort, on its default CLI (codex) |
sol:xhigh | the same model, thinking harder |
sol:xhigh:openclaude | the same model and effort, through openclaude |
opus::claude | opus on claude, effort left to the default |
gpt-5.6-sol::codex | a model id forge doesn't know, passed straight through; only with a CLI named |
The alias comes from forge's registry, registry.tsv: today sol, astra, terra, luna, opus, sonnet, fable, haiku, gemini, gemini-pro, grok, kimi, glm, qwen and a few more. Each alias's first row is its default CLI. forge never guesses a CLI for a model it doesn't know: that guess could spend quota on the wrong provider.
Effort, and when forge lowers it
| CLI | Efforts |
|---|---|
| codex | low medium high xhigh max ultra |
| claude | low medium high xhigh max |
| openclaude | low medium high xhigh max ultracode |
| grok | low medium high xhigh max (grok-4.7 up to xhigh) |
| antigravity | low medium high |
| opencode | depends on the provider; passed through as written |
Models have ceilings and gaps: luna tops out at max, and gemini-pro offers low and high but not medium. When you ask for more than a model offers, forge lowers it and says so (clamped=ultra -> max). Some CLIs quietly run at another level when given one they don't support; forge checks first, so you never get less thinking than you paid for without knowing. A word that isn't an effort at all is an error.
Defaults when you leave things out
- No
--dwarf: forge asks. Every dispatch spends your quota. - No
--qa:opusathigh, through Claude Code. - No effort: a dwarf builds at
medium, a reviewer reviews athigh, a planner plans atxhigh. A reviewer thinking less than its builder tends to wave things through.
Profiles: routing you can name
A profile keeps routing, retry policy and budgets under a name. forge ships two, measured on benchmark runs:
| Difficulty | Builds with | Reviewed by |
|---|---|---|
| low | haiku:xhigh | sonnet:medium |
| medium | sonnet:medium | sonnet:high |
high, balanced | opus:high | opus:high |
high, lite | sonnet:high | sonnet:high |
Both retry a failed task up to twice and move it to a stronger model after two failures.
/forge "add CRUD endpoints for projects, users and teams" --decompose-level medium --profile balanced forge config profile show balanced # everything it sets forge config profile create mine --from balanced # your own copy forge config profile use mine # make it the default
A run freezes a copy of its profile, so editing a profile later never changes a run in flight. --fast dwarf,qa asks for the fast service tier on chosen roles. Only Codex and Claude offer it, and it's billed at a higher rate, which the approval table says.
Dropping the sandbox
--yolo-dwarf and --yolo-qa run one role without its sandbox and approval prompts, for work that installs packages, writes outside the repo or uses the network. Usually you want --yolo-dwarf alone.
Antigravity needs it to run anything. Without --yolo-dwarf an Antigravity dwarf can't run a single shell command, and one refusal ends its whole run. forge tells it not to try, so its work arrives untested.
Teaching forge a new model
Add one line to registry.tsv: alias, CLI, model id, efforts, and optionally a timeout. Nothing else changes.
# alias harness model effort [timeout]
sol codex gpt-6.1-sol <=ultra
gemini-pro antigravity gemini-3.1-pro low,high
opus antigravity claude-opus-4-6-thinking none
<=X means any effort up to X, a,b exactly those, none takes no effort flag, - passes it through unchecked.
Full reference Every flag and edge case: docs/models.md