Model tiers
Every agent xiv launches has an explicitly chosen model and reasoning effort, resolved once per run from environment variables in pack/agents.ts. The defaults form a cheap tier that is plenty when the work is fully spec'd in Linear; XIV_TIER=quality raises the steps where capability actually buys something. Both providers take an explicit effort, so a tier can be raised by model, by effort, or by both.
Two providers, one mixed pipeline
xiv runs a mix of Claude Code and Codex agents — the point is a mixed pipeline, not a single provider:
- Claude supplies a heavy model (sustained multi-file editing, judgment-heavy autonomy) and a light model (shelling out to lint/test and reading output).
- Codex supplies a general model, a light model for mechanical steps, a planner, and a reviewer. GPT‑5.6 names its capability tiers (
sol>terra>luna) so they can advance independently of the generation number — the cost lever is model and effort, not model alone.
| Role | Cheap (default) | Quality (XIV_TIER=quality) |
|---|---|---|
| Claude heavy | claude-sonnet-5 @ medium | claude-opus-5 @ xhigh |
| Claude light | claude-haiku-4-5 @ low | claude-sonnet-5 @ low |
| Claude auto-light (mechanical git/gh work) | claude-sonnet-5 @ low — pinned, not tiered | same |
| Codex general | gpt-5.6-terra | gpt-5.6-sol |
| Codex light | gpt-5.6-luna @ low | same |
| Codex planner | gpt-5.6-sol @ low | gpt-5.6-sol @ xhigh |
| Codex reviewer | gpt-5.6-terra @ high | gpt-5.6-sol @ high |
The auto-light row is pinned on purpose: paying Opus rates to write a commit message buys nothing. Genuinely hard autonomous work — the jj re-flow in stack-amend — runs on the tiered heavy model instead.
Per-step assignment in the implement loop
Each linear-implement step carries a balanced engine default, each with a reason (from the source comments):
| Step | Engine default | Cheap | Quality | Why it lands there |
|---|---|---|---|---|
| fetch-issue | codex | gpt-5.6-luna @ low | same | an MCP call and a transcription; no reasoning to pay for |
| plan | codex | gpt-5.6-sol @ low | gpt-5.6-sol @ xhigh | the step whose quality most determines the run — tiered by effort, not model |
| implement | claude | claude-sonnet-5 @ medium | claude-opus-5 @ xhigh | sustained multi-file editing, where Claude Code's harness earns its keep |
| validate | codex | gpt-5.6-luna @ low | same | the loop's arbiter, but it arbitrates on command exit codes, not judgment |
| review | codex | gpt-5.6-terra @ high | gpt-5.6-sol @ high | findings must be trustworthy; a false approval ends the loop |
| finalize | claude | claude-sonnet-5 @ low | same | branch, commit, report — mechanical, plus bypassed permissions and the never-merge rule |
Only three steps change between tiers; the other three are mechanical, so capability buys nothing.
The stack planner is off the ladder
xiv stack plan runs claude-fable-5 at xhigh in both tiers (overridable with XIV_STACK_PLAN_MODEL / XIV_STACK_PLAN_EFFORT; in all-codex mode it falls back to the codex planner). Stack planning is the single highest-leverage call in the lifecycle: it decides which issues enter the stack, in what order, and against which repo — and because each entry is built on top of the previous one's branch, every later command inherits that ordering from the stack map. Getting it wrong is not a bad paragraph, it is a rebuild. It also runs exactly once per feature, so the most capable model at high effort costs a rounding error next to the N build subflows it governs.
Shared agent pools
Workflows outside the implement loop draw from named pools: cheapFast, smart, smartTool, and autonomous (heavy model + bypassPermissions + the never-merge system prompt). By default the pools are pure Claude — codex is flaky on structured output, so keeping it out of the shared pools means a codex member can never end up running on every build. XIV_ENGINE=codex replaces every pool member (and every per-step assignment) with codex agents instead.
Environment-variable override matrix
All of these are read once at run start, so a run can be retargeted without editing the pack — e.g. XIV_TIER=quality xiv stack build --feature payments --all-repos.
Global knobs
| Env var | Default | Effect |
|---|---|---|
XIV_TIER | cheap | quality raises implement to Opus 5 @ xhigh, review to Sol, plan to xhigh |
XIV_ENGINE | claude | codex runs every step and pool on codex only (e.g. to spare the Claude subscription limit) |
XIV_AGENT_MAX_USD | (none) | hard per-agent spend cap — applied to Claude agents (Codex agents take no budget flag) |
Claude knobs
| Env var | Default (cheap) | Effect |
|---|---|---|
XIV_MODEL_HEAVY | claude-sonnet-5 | model for implement + judgment-heavy autonomous work |
XIV_MODEL_LIGHT | claude-haiku-4-5 | Claude model for mechanical steps (does not change the pinned finalize model) |
XIV_EFFORT_HEAVY | medium (xhigh on quality) | heavy effort: low | medium | high | xhigh | max |
XIV_EFFORT_LIGHT | low | light effort (also applies to the pinned auto-light agent) |
Codex knobs
| Env var | Default (cheap) | Effect |
|---|---|---|
XIV_CODEX_MODEL | gpt-5.6-terra (sol on quality) | codex model for the general/autonomous codex agent |
XIV_CODEX_LIGHT_MODEL | gpt-5.6-luna | codex model for the mechanical steps |
XIV_PLAN_MODEL | gpt-5.6-sol | codex plan model (both tiers) |
XIV_REVIEW_MODEL | gpt-5.6-terra (sol on quality) | codex review model (always at high effort) |
XIV_CODEX_REASONING | low (medium on quality or in all-codex mode) | reasoning effort for the general codex agent |
Stack planner
| Env var | Default | Effect |
|---|---|---|
XIV_STACK_PLAN_MODEL | claude-fable-5 | stack planner model |
XIV_STACK_PLAN_EFFORT | xhigh | stack planner effort |
Per-step engine overrides
Each forces one linear-implement step onto the named provider for that run; XIV_ENGINE=codex overrides them all.
| Env var | Default engine |
|---|---|
XIV_FETCH_ENGINE | codex |
XIV_PLAN_ENGINE | codex |
XIV_VALIDATE_ENGINE | codex |
XIV_REVIEW_ENGINE | codex |
XIV_IMPLEMENT_ENGINE | claude |
XIV_FINALIZE_ENGINE | claude |
An invalid effort value falls back to the default rather than being trusted — env input is external input.
Effort compatibility
--effort is a 5-family Claude capability (plus Opus/Sonnet 4.6+); the 4.5-generation models reject the flag outright, so a cheap-tier step on Haiku would die at startup if it were passed unconditionally. Effort is therefore attached only to models on a known-compatible list (claude-fable-5, claude-opus-5, claude-sonnet-5, claude-opus-4-8, claude-opus-4-7, claude-opus-4-6, claude-sonnet-4-6). Anything unrecognized — including a custom XIV_MODEL_* override — silently inherits the CLI's own default effort, which is the safe direction to fail. The list is about flag compatibility, not about which models xiv actually uses.
All-codex mode caveats
Two things to know before setting XIV_ENGINE=codex:
- The path needs a model your codex login actually serves: the
-codex-suffixed model variants require anOPENAI_API_KEYand return 400 on a ChatGPT-subscription login, while the plain tiers work. - A codex step fails at startup when a stdio MCP server registered in
~/.codex/config.tomlcannot be reached — a server pointed at a local port only serves while that app is running. Comment such an entry out rather than leaving it registered.
Where this configuration lives
These are pack settings: the env vars work per-run with no install step, but changing the defaults means editing pack/agents.ts and running xiv update so the managed pack in SMITHERS_HOME picks it up — unless you are iterating with xiv dev, which runs the in-repo pack directly (see authoring).