forgev0.19
Docs pages

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 writeforge runs
solsol at the role's default effort, on its default CLI (codex)
sol:xhighthe same model, thinking harder
sol:xhigh:openclaudethe same model and effort, through openclaude
opus::claudeopus on claude, effort left to the default
gpt-5.6-sol::codexa 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

CLIEfforts
codexlow medium high xhigh max ultra
claudelow medium high xhigh max
openclaudelow medium high xhigh max ultracode
groklow medium high xhigh max (grok-4.7 up to xhigh)
antigravitylow medium high
opencodedepends 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: opus at high, through Claude Code.
  • No effort: a dwarf builds at medium, a reviewer reviews at high, a planner plans at xhigh. 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:

DifficultyBuilds withReviewed by
lowhaiku:xhighsonnet:medium
mediumsonnet:mediumsonnet:high
high, balancedopus:highopus:high
high, litesonnet:highsonnet: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