AI Model Selection

Updated on Oct 5, 2026

Configure which AI model Forge passes to your coding agent. Set one default model, override it for a workflow target or a single operation, or generate everything from a model profile.

Forge does not rank models or route requests by cost or latency. It picks the model name from your configuration and passes it to the agent, and the agent decides whether that model is available.

Prerequisites

A supported agent is installed and authenticated. See AI Coding Agent Setup.

How Forge resolves the model

A target is a workflow area, such as issue, code, or pr. An operation is a target plus an action, written target.operation, such as issue.draft or pr.review.

For each command, Forge uses the first model it finds in this order:

The -m, --model <MODEL> command-line option.
The operations entry for the operation, for example "issue.draft".
The targets entry for the target, for example issue.
The agent-level model setting.
No model. The agent uses its own default.

Forge uses the same most-specific-first order for prompt formats and custom agents.

Model profiles

A profile generates .forge/config/agents.toml with a default model and operation overrides for the selected agent:

bash

frg config init --agent claude_code --models balanced

Profile	Purpose
`lite`	Minimize costs with fast, inexpensive models.
`balanced`	Good performance at reasonable cost.
`stable`	Predictable behaviour. This is the default when you pass `--agent` without `--models`.
`heavy`	Maximum quality for critical operations.

Profile names are case-insensitive. --models requires --agent. A profile does not install the agent, select an account, or check that the models are available.

If agents.toml already exists, Forge keeps it. Add --force to regenerate it.

Generated models

In the tables, key operations means issue.draft, issue.plan, issue.review, pr.review, and pr.merge.

github_copilot claude_code opencode

Profile	Default `model`	Operation overrides
`lite`	`gpt-5.4-mini`	Key operations use `gpt-5.4`.
`balanced`	`gpt-5.4`	Key operations use `gpt-5.5`.
`stable`	`claude-sonnet-5`	`issue.plan` uses `claude-opus-5`.
`heavy`	`gpt-5.5`	None.

Profile	Default `model`	Operation overrides
`lite`	`claude-haiku-5`	Key operations use `claude-sonnet-5`.
`balanced`	`claude-sonnet-5`	Key operations use `claude-opus-5`.
`stable`	`claude-sonnet-5`	`issue.plan` uses `claude-opus-5`.
`heavy`	`claude-opus-5`	None.

OpenCode works with many model providers, so every generated model value is auto. The overrides have the same shape as the other agents: key operations for lite and balanced, issue.plan only for stable, and none for heavy.

Replace each auto with a model from your provider, in provider/model form. The comments in the generated file show which tier each entry should use. For example:

toml

[agent.opencode]
model = "anthropic/claude-sonnet-5"

[agent.opencode.operations]
"issue.plan" = "anthropic/claude-opus-5"

Configure models manually

Keep model settings in the agent's table in .forge/config/agents.toml.

Set a default model

toml

schema_version = "1.0.0"

[agent]
default = "github_copilot"

[agent.github_copilot]
model = "claude-sonnet-5"

Override by target

toml

[agent.github_copilot.targets]
issue = "claude-haiku-5"
code = "claude-opus-5"

With the default model from the previous example:

frg issue draft uses claude-haiku-5.
frg code review uses claude-opus-5.
frg pr draft uses the default, claude-sonnet-5.

A target entry can also be a table that sets model, prompt_format, custom_agent, and commit settings together, for example code = { model = "claude-opus-5", prompt_format = "xml" }.

Override by operation

toml

[agent.github_copilot.operations]
"issue.draft" = "claude-opus-5"
"code.review" = "gpt-5.5"

The operation entry wins over the issue target entry, so frg issue draft uses claude-opus-5 while frg issue triage still uses the target model.

Override for one command

bash

frg code review --model claude-opus-5

Model name validation

Forge checks model names for structural problems only. Names must be non-empty, no longer than 128 bytes, and use alphanumeric characters, dashes, underscores, dots, and at most one slash separating non-empty provider and model segments. A segment must start with an alphanumeric character and cannot contain consecutive special characters. Validation warnings identify the specific structural issue; they do not mean that Forge has checked whether a model exists.

The <location> in a warning, such as model, targets.code, or operations.issue.plan, identifies the configuration entry. Model names are case-sensitive. Forge passes a structurally valid name to the agent, which determines whether the model is available and reports any provider-specific rejection. See Effort Levels to configure reasoning effort separately from model selection.

Automatic model selection

You can set model = "auto" and let the agent choose. Forge passes auto through unchanged, and the agent decides what it means. This is not recommended for team workflows because output quality and cost vary more between runs. Pin important operations to specific models instead:

toml

[agent.github_copilot]
model = "auto"

[agent.github_copilot.operations]
"issue.plan" = "claude-opus-5"

Troubleshooting

--agent flag is required when using --models

Cause: You ran frg config init --models <PROFILE> without --agent.

Solution:

Add an agent ID:

bash

frg config init --agent github_copilot --models stable

Invalid profile: ''. Valid options: lite, balanced, stable, heavy

Cause: The --models value is not a supported profile.

Solution:

Use lite, balanced, stable, or heavy.

A model setting is ignored

Cause: A higher-precedence setting applies, or the key does not match the command.

Solution:

Check for --model on the command line.
Confirm that the table name matches agent.default, for example [agent.github_copilot.operations] when the default is github_copilot.
Confirm that operation keys use target.operation and match the command, for example "pr.review" for frg pr review.
Run frg config validate --file .forge/config/agents.toml and fix any warnings.

Verify: Run frg config show to see the resolved agent configuration.

The agent rejects the model

Cause: The provider does not offer the model, or the name is wrong for that agent. Forge's validation checks the format only.

Solution:

Check the exact model name in the agent's documentation.
Test the model directly with the agent CLI.
Update agents.toml, or pass --model to test a different name.

Model Used for Health Checks

frg status, frg config validate, and the learn readiness check confirm that your coding agent is authenticated by sending it a very short prompt. There is no free way to ask an agent CLI whether it is signed in, so this check consumes a small number of tokens each time you run one of those commands.

To keep that cost predictable, Forge sends the check with the model you already configured for that agent, instead of letting the agent CLI pick one automatically:

If you set an agent-level model in .forge/config/agents.toml, Forge uses exactly that model for the check. frg config init writes this value for you, so it is normally already set.
If no agent-level model is set, Forge sends no model name at all and the agent CLI applies its own default.

Forge has no separate "health check model" and no built-in model name of its own. It will never send a model you did not configure. That keeps the check honest — it verifies the model your real runs use — and means you control the cost by choosing a cheaper agent-level model if you want to.

Target-level and operation-level model settings do not apply to the health check. The check is not a workflow operation, so only the agent-level model is used.

Normal workflow commands are unaffected: they do not run this check and continue to use the full model resolution order described above.