Choose a model

Pick, switch and pin models in Hull, and decide between Auto, a specific model, your own provider or a local model.

Every Hull session runs on a model. You can let Auto pick one for each step, choose a specific model yourself, or connect your own provider account. This page covers how to select and switch models and how to think about the choice.

Your options

Option	What it is	Where to start
Auto	Hull Gateway picks a model for each request.	Auto model
A specific Hull Gateway model	Choose a named model and its reasoning settings. Usage counts against your plan.	Hull Gateway
Your own provider account	Connect Anthropic, OpenAI, Google, OpenRouter and others with your own credentials.	Providers
Local models	Run models on your machine with Ollama, LM Studio, Atomic Chat or Anaconda Desktop.	Local models
Custom models	Register a model that isn't in the catalog, such as a fine-tune or a new release.	Custom models

Select and switch models

Use the model selector in the chat prompt area to pick a model for the current session, or type /models to open the picker.
When the selected model supports variants (such as reasoning effort), type /variant to choose one.
Set a global default and per-agent defaults in Settings (under Model per Mode), or in your hull.jsonc config file.
The selector remembers the last model you picked for each agent. Switching agents restores your previous choice. A manual pick always beats config; use the reset button (shown when your active model differs from config) to go back to the configured default.
Precedence: session override, then last pick for the agent, then per-agent config, then global config, then Auto Free.

Model IDs use the format provider_id/model_id, for example anthropic/claude-sonnet-4-5, or hull/hull-auto/frontier for an Auto tier on Hull Gateway.

How to choose

Not sure? Use Auto. Auto Frontier routes planning and debugging to stronger models and implementation to faster ones.
Complex work (large refactors, architecture, hard bugs): frontier models from Anthropic, OpenAI and Google usually handle nuance best.
Everyday coding: mid-tier models give a good balance of speed, cost and quality.
Cost-sensitive work: Auto Efficient routes each request to the cheapest model that is accurate enough for it.
Private or offline work: local models keep everything on your machine, at the cost of speed and capability.

Context windows

Context window size affects how much of your project a model can hold at once.

Small projects (scripts, components): 32K to 64K tokens is enough.
Standard applications: 128K tokens covers most multi-file work.
Large codebases: 256K tokens or more helps with cross-system changes.
1M-token models exist, but quality can drop at the extremes.

If you hit a context limit error, delete a message, roll back to an earlier checkpoint, or switch to a model with a longer context window for that turn.

Models for subagents

When an agent delegates work to a subagent (through the task tool), the subagent uses the parent's model by default. To pin a model for a specific subagent, set it in config:

{
  "agent": {
    "explore": {
      "model": "anthropic/claude-haiku-4-5"
    }
  }
}

In VS Code you can set the same override in Settings under Model per Mode. Both write the same agent.<name>.model entry. See Custom subagents.

Select a model or agent from a link (VS Code)

The VS Code extension handles vscode:// links that open VS Code and select a model, an agent, or both. Use them to share a setup or launch a specific Auto tier from a web page.

vscode://hullcode.hull-code/hullcode/switch?model=<modelID>
vscode://hullcode.hull-code/hullcode/switch?agent=<agentName>
vscode://hullcode.hull-code/hullcode/switch?model=<modelID>&agent=<agentName>

model must be a model in the current Hull Gateway catalog, such as hull-auto/free. URL-encode the slash as %2F.
agent must be a visible primary agent ID, such as code or plan.

For example, this link opens Hull Code with Auto Free in the Plan agent:

vscode://hullcode.hull-code/hullcode/switch?model=hull-auto%2Ffree&agent=plan

How it behaves:

If VS Code is open, the Hull sidebar is focused and the selection applies to the active session. If it's closed, VS Code launches and applies the selection once the extension is ready.
Invalid or unavailable models or agents are ignored.
With both parameters, the agent is selected first so the model applies to it.
The link changes the active (or next) session only. It does not change your configured defaults.

Your optionsCopy Anchor Link

Select and switch modelsCopy Anchor Link

How to chooseCopy Anchor Link

Context windowsCopy Anchor Link

Models for subagentsCopy Anchor Link