Search documentation

Search the Fumadocs-backed documentation index.

Models

Which models the agents run, with per-entry controls like effort and context window.

models defines which models run, as an independent axis cross-multiplied with agents. Listing agents: [claude] with models: [opus, sonnet] produces both variants without duplicating the agent.

Accepted shapes:

# String form: one model.
models: claude-opus-4-8

# List of strings: multiple models.
models:
  - claude-opus-4-8
  - claude-sonnet-4-6

# Object form: a model with controls.
models:
  - name: gpt-5.3-codex
    effort: high

models is optional. If omitted, each agent runs its provider-default model.

Pruning incompatible pairs

The agents × models cross product keeps only the compatible pairs. A model the catalog knows for a different agent's provider — for example claude × an openai model — is pruned (dropped), not an error, so one agents + models pair of lists expresses every valid combination:

agents: [claude, codex]
models: [claude-opus-4-8, gpt-5.3-codex]
# 2 × 2 = 4 pairs → pruned to the 2 valid ones:
#   ✓ claude + claude-opus-4-8     ✓ codex + gpt-5.3-codex
#   ✗ claude + gpt-5.3-codex       ✗ codex + claude-opus-4-8   (dropped)

Pruning is visible — dropped pairs show up as a smaller resolved matrix in ax experiment variants. If a listed agent or model is compatible with nothing else listed (every pair it appears in is pruned), ax experiment validate hard-errors, since that entry is almost certainly a typo.

Model id format

Prefer the lab-official models.dev id with no owner prefix, such as claude-opus-4-8, gpt-5.3-codex, or composer-2.5. AX infers the runtime provider from the selected agent and stores a canonical provider/lab/model id behind the scenes.

If a bare id is ambiguous, validation asks for lab; use the model object form, for example { name: claude-opus-4-8, lab: anthropic }. Most model ids do not need this.

Older owner/provider-prefixed and gateway-style ids, such as anthropic/claude-opus-4-8 or anthropic/claude-opus-4.8, are accepted for compatibility and normalize to the same canonical id.

Model object

A model object configures one model and its controls. Optional controls are passed through when the selected agent supports them. To compare two control settings of the same model, list two models entries.

FieldRequiredType / valuesNotes
nameYesStringLab-official models.dev id, such as claude-opus-4-8 or gpt-5.
labNoStringOptional disambiguator, such as anthropic or openai, used only when validation reports an ambiguous bare id.
effortNolow, medium, high, x-high, maxReasoning effort control, validated against the (agent, model) catalog. Delivered where each harness honors it: an ACP session/set_config_option for Claude / Codex, baked into the model id for Cursor.
context_window_sizeNoStringContext window size, such as 1M or 200k (a token count also works). Supported for Claude (200k or 1M) and Codex (any size up to the model's limit). Not supported for Cursor — the Cursor CLI cannot select a context window, so ax experiment validate (and therefore ax experiment run / ax experiment run --local) rejects any Cursor variant that sets it. Validation also rejects sizes over the selected model's limit.
thinkingNoBooleanEnables thinking mode when supported.
fastNoBooleanEnables fast mode when supported.
agents: [claude, codex]
models:
  - name: claude-opus-4-8
    effort: high
    context_window_size: 1M
    thinking: true
  - gpt-5