I open the same repository from two places: the terminal inside my editor during the day, and a separate shell at night. One evening I noticed that only the night sessions were starting on a model several generations old.
The culprit turned out to be me, a few months earlier. I had wanted to pin a model for a short experiment, so I added export ANTHROPIC_MODEL=... to ~/.zshrc and never took it out. Nothing in the UI shows a variable that lives in a shell profile. It gets injected silently every time, and the only clue I had was a vague sense that the answers felt different.
When ANTHROPIC_DEFAULT_MODEL arrived in v2.1.236, my first thought was that I could simply switch to it. That was wrong. Later I tripped over a second trap as well: the moment you save a choice with /model, the new variable stops being used at all. This post walks through both, in the order I ran into them.
The short version: ANTHROPIC_DEFAULT_MODEL is last of five
The official Model configuration page (checked in November 2026) lists the ways to set a model, strongest first:
/modelduring a sessionclaude --modelat startup- the
ANTHROPIC_MODELenvironment variable - the
modelfield in a settings file - the
ANTHROPIC_DEFAULT_MODELenvironment variable
The new variable is at the bottom. Per the docs, a new session starts on its model only when none of these selects one: --model, ANTHROPIC_MODEL, a model value in any settings file, or an organization default model.
Number four is the one people miss. Pressing Enter in the /model picker saves your choice by writing model into ~/.claude/settings.json. So the first time you pick a model that way, your user settings gain a model field, and ANTHROPIC_DEFAULT_MODEL is never consulted again on later launches.
The two variables do not replace each other
ANTHROPIC_MODEL means "come back to this value on every launch." You can still switch with /model mid-session, but the next launch starts on the variable's model regardless of what you saved. ANTHROPIC_DEFAULT_MODEL means "use this only if nothing else has decided."
One snaps back no matter what you do; the other steps aside the moment anything else speaks. Adding the second does nothing to the first.
| Where the model is set | Official rank | What happens on the next launch | How easy to forget |
|---|---|---|---|
/model, then Enter | 1 (immediately) | Saved to model in user settings, so it keeps applying as rank 4 | Medium (you forget you picked it) |
/model picker, then s | 1 (immediately) | This session only; nothing is saved | Low |
claude --model | 2 | Only the session launched with it | Low |
ANTHROPIC_MODEL | 3 | Comes back to this value every time | High (invisible in a shell profile) |
ANTHROPIC_MODEL inside a settings file's env block | Treated like 3 | Comes back every time in that project | High (missed if you only read the model field) |
model in a settings file | 4 (local > project > user) | Starts on the value from the closest file | Low (it is a visible file) |
ANTHROPIC_DEFAULT_MODEL | 5 | Used only when none of the above is set | Medium |
What makes this tiresome is that seven entry points hold the same kind of string, a model name, with different behavior, and two of them sit where you rarely look. I went back and forth between /status and my settings files more times than I would like to admit.
Three misunderstandings, corrected from the docs
"Adding the new variable overrides the old one." It is the other way around. As long as ANTHROPIC_MODEL is set, ANTHROPIC_DEFAULT_MODEL is never read. Remove the old variable before you add the new one.
"I picked it with /model, so the next session will use it." With ANTHROPIC_MODEL set, your saved choice is kept but outranked; the docs say exactly that. The same applies when project or managed settings set model, and in that case the startup header names the file responsible.
"ANTHROPIC_DEFAULT_MODEL=haiku makes a lighter model my default." The docs say the variable is ignored when its value is default, inherit, opusplan, or haiku. It is also ignored when an admin turns on enforceAvailableModels, or when organization restrictions exclude the model. When it does take effect, the Default row in the /model picker carries the label "Set by ANTHROPIC_DEFAULT_MODEL", and that label is how I check.
One more note: the environment variable reference marks ANTHROPIC_SMALL_FAST_MODEL as deprecated. ANTHROPIC_DEFAULT_HAIKU_MODEL now covers both what the haiku alias resolves to and background tasks.
Working backward from the symptom
| Symptom | Likely cause | How to check | Fix |
|---|---|---|---|
| Only new shells start on an old model | export ANTHROPIC_MODEL in a shell profile | env | grep ANTHROPIC in a fresh shell | Delete the line and open a new shell |
You set ANTHROPIC_DEFAULT_MODEL and nothing changed | Some settings file has model (including one saved by /model) | Does the Default row show "Set by ANTHROPIC_DEFAULT_MODEL"? | Remove model from settings, or put your default there instead |
Your /model choice reverts on relaunch | ANTHROPIC_MODEL, or model in project or managed settings | Does the startup header name a settings file? Is the variable in env? | Remove the pin, or confirm the project setting is intended |
| It starts fine, then the first message fails | The pinned ID is retired or mistyped | The error reads There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. | Find the pin and switch to an alias or a current ID |
| Only resumed sessions use a different model | --resume and --continue keep the model the session was saved on | Compare against a fresh session | Pass --model when resuming |
The official errors page says it plainly about the fourth row: if the wrong model keeps coming back, a stale ID is set somewhere. Claude Code does not reject the value at startup, so the failure appears one step later, which is exactly what makes it hard to trace.
List everything that could be deciding your model
What I needed was not a guess about which setting wins, but one screen showing everything that is set. So I wrote a small script that collects environment variables, the three settings files, and shell profiles, then numbers each entry by its official rank. My earlier version only split entries into "pinned" and "default," which meant it could not show a settings-file model beating ANTHROPIC_DEFAULT_MODEL. This version fixes that.
#!/usr/bin/env python3
"""List everything that can decide Claude Code's startup model, then report the winner and any retiring IDs.
Usage:
python3 model_sources.py [project root]
The order follows the official Model configuration page (checked November 2026):
/model (in session) > --model > ANTHROPIC_MODEL > model in a settings file > ANTHROPIC_DEFAULT_MODEL
This script cannot see --model, an organization default model, or managed settings.
"""
import datetime
import json
import os
import re
import sys
import unicodedata
HOME = os.environ.get("MODEL_SOURCES_HOME") or os.path.expanduser("~")
TODAY = datetime.date.fromisoformat(
os.environ.get("MODEL_SOURCES_TODAY") or datetime.date.today().isoformat()
)
# From the official model retirement table: the IDs most likely to linger in local config (Nov 2026)
RETIREMENTS = {
"claude-sonnet-4-5-20250929": "2026-11-30",
"claude-sonnet-4-5": "2026-11-30",
"claude-opus-4-1-20250805": "2026-08-05",
}
# Claude Code ignores ANTHROPIC_DEFAULT_MODEL when it holds one of these
IGNORED_DEFAULTS = {"default", "inherit", "opusplan", "haiku"}
# Lower number wins. Settings files rank local > project > user
RANK = {"pin": 1, "local": 2, "project": 3, "user": 4, "default": 5}
SETTINGS_FILES = [
("user", "user settings", os.path.join(HOME, ".claude", "settings.json")),
("project", "project settings", os.path.join("{root}", ".claude", "settings.json")),
("local", "local settings", os.path.join("{root}", ".claude", "settings.local.json")),
]
PROFILES = [".zshrc", ".zshenv", ".zprofile", ".bashrc", ".bash_profile", ".profile"]
SHELL_LINE = re.compile(r"(ANTHROPIC_(?:DEFAULT_)?MODEL)=[\"']?([^\"'\s#]+)")
JSONC_COMMENT = re.compile(r"^\s*//")
def load_jsonc(path):
"""Read JSON that may contain // comments. Never crash; return the reason instead."""
try:
with open(path, encoding="utf-8") as fh:
body = "".join(l for l in fh if not JSONC_COMMENT.match(l))
return json.loads(body), None
except FileNotFoundError:
return None, None
except (json.JSONDecodeError, OSError) as exc:
return None, f"could not read: {exc}"
def retirement(value):
"""Return (date, days left) when the ID has a scheduled retirement."""
day = RETIREMENTS.get(value.replace("[1m]", ""))
if not day:
return None
return day, (datetime.date.fromisoformat(day) - TODAY).days
def collect(root):
rows = [] # (origin, where, value, rank or None, note)
if os.environ.get("ANTHROPIC_MODEL"):
rows.append(("env var", "ANTHROPIC_MODEL", os.environ["ANTHROPIC_MODEL"], RANK["pin"],
"every launch comes back to this"))
if os.environ.get("ANTHROPIC_DEFAULT_MODEL"):
rows.append(("env var", "ANTHROPIC_DEFAULT_MODEL", os.environ["ANTHROPIC_DEFAULT_MODEL"],
RANK["default"], "used only when no settings file sets model"))
if os.environ.get("ANTHROPIC_SMALL_FAST_MODEL"):
rows.append(("env var", "ANTHROPIC_SMALL_FAST_MODEL", os.environ["ANTHROPIC_SMALL_FAST_MODEL"],
None, "deprecated; move it to ANTHROPIC_DEFAULT_HAIKU_MODEL"))
for level, label, template in SETTINGS_FILES:
path = template.format(root=root)
data, error = load_jsonc(path)
if error:
# Silently skipping broken JSON hides the real cause of "I set it and nothing changed"
rows.append((label, path, "-", None, error))
continue
if not data:
continue
if data.get("model"):
rows.append((label, path, data["model"], RANK[level], "model in a settings file"))
env = data.get("env") or {}
if env.get("ANTHROPIC_MODEL"):
rows.append((label, path, env["ANTHROPIC_MODEL"], RANK["pin"],
"env block injects ANTHROPIC_MODEL"))
if env.get("ANTHROPIC_DEFAULT_MODEL"):
rows.append((label, path, env["ANTHROPIC_DEFAULT_MODEL"], RANK["default"],
"env block injects ANTHROPIC_DEFAULT_MODEL"))
for name in PROFILES:
path = os.path.join(HOME, name)
try:
with open(path, encoding="utf-8") as fh:
lines = fh.readlines()
except OSError:
continue
for lineno, line in enumerate(lines, 1):
match = SHELL_LINE.search(line)
if match and not line.lstrip().startswith("#"):
rows.append(("shell profile", f"{path}:{lineno}", match.group(2), None,
f"exports {match.group(1)} in every new shell"))
return rows
def width(text):
return sum(2 if unicodedata.east_asian_width(ch) in "WF" else 1 for ch in text)
def pad(text, size):
return text + " " * max(0, size - width(text))
def main():
root = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
rows = collect(root)
if not rows:
print("Nothing here sets a model (your account default applies)")
return 0
size = max(width(r[0]) for r in rows)
for origin, where, value, rank, note in rows:
print(f"{pad(origin, size)} rank {rank or '-'} {value}")
print(f"{' ' * size} └ {where} — {note}")
warnings = []
live = [r for r in rows if r[3] is not None]
for r in live:
if r[3] == RANK["default"] and r[2] in IGNORED_DEFAULTS:
warnings.append(f"ANTHROPIC_DEFAULT_MODEL={r[2]} is ignored")
live = [r for r in live if not (r[3] == RANK["default"] and r[2] in IGNORED_DEFAULTS)]
pins = sorted({r[2] for r in live if r[3] == RANK["pin"]})
if len(pins) > 1:
warnings.append(f"ANTHROPIC_MODEL is set to {len(pins)} different values: {', '.join(pins)}")
for r in rows:
hit = retirement(r[2])
if hit:
day, left = hit
state = "already retired" if left <= 0 else f"{left} days left"
warnings.append(f"{r[2]} retires on {day} ({state}): {r[1]}")
print()
if live:
winner = min(live, key=lambda r: r[3])
tied = sorted({r[2] for r in live if r[3] == winner[3]})
if len(tied) > 1:
# The docs do not say which of two equal-rank values wins, so do not guess
print(f"→ {len(tied)} values share rank {winner[3]}; confirm the winner with /status")
else:
print(f"→ wins at startup: {winner[2]} ({winner[1]})")
losers = sorted({r[2] for r in live if r[3] > winner[3]} - set(tied))
if losers:
print(f" never consulted: {', '.join(losers)}")
for w in warnings:
print(f"⚠ {w}")
return 1 if warnings else 0
if __name__ == "__main__":
sys.exit(main())Four choices here are deliberate.
First, it reads inside each settings file's env block. If you only look at the model field and conclude the project settings are irrelevant, you miss the hardest pin to spot.
Second, broken JSON shows up as a row instead of being swallowed. A file skipped for a syntax error produces the symptom "I set it and nothing changed," and that gap between cause and symptom is exactly what I did not want to hide.
Third, when two values share the same rank, it refuses to name a winner. I could not find anything in the docs that says whether a shell-exported ANTHROPIC_MODEL beats one from a settings file's env block, and I have not confirmed it myself. Guessing would turn the script into a new source of the same confusion.
Fourth, it warns about IDs with a scheduled retirement. The table copies only the entries from the official model deprecations page that tend to linger in local config. When a new retirement is announced, I add one line.
What it printed on my machine
Here is the output against a setup modeled on mine, with the date fixed to November 19, 2026:
env var rank 1 claude-sonnet-4-5-20250929
└ ANTHROPIC_MODEL — every launch comes back to this
env var rank 5 claude-sonnet-5-5
└ ANTHROPIC_DEFAULT_MODEL — used only when no settings file sets model
user settings rank 4 claude-opus-5
└ /home/me/.claude/settings.json — model in a settings file
project settings rank 3 claude-opus-5
└ /work/proj/.claude/settings.json — model in a settings file
project settings rank 1 claude-opus-5
└ /work/proj/.claude/settings.json — env block injects ANTHROPIC_MODEL
local settings rank 2 claude-haiku-4-5-20251001
└ /work/proj/.claude/settings.local.json — model in a settings file
shell profile rank - claude-sonnet-4-5-20250929
└ /home/me/.zshrc:2 — exports ANTHROPIC_MODEL in every new shell
shell profile rank - claude-sonnet-5-5
└ /home/me/.bash_profile:1 — exports ANTHROPIC_DEFAULT_MODEL in every new shell
→ 2 values share rank 1; confirm the winner with /status
never consulted: claude-haiku-4-5-20251001, claude-sonnet-5-5
⚠ ANTHROPIC_MODEL is set to 2 different values: claude-opus-5, claude-sonnet-4-5-20250929
⚠ claude-sonnet-4-5-20250929 retires on 2026-11-30 (11 days left): ANTHROPIC_MODEL
⚠ claude-sonnet-4-5-20250929 retires on 2026-11-30 (11 days left): /home/me/.zshrc:2Six entries could decide the model. The local Haiku and the ANTHROPIC_DEFAULT_MODEL Sonnet 5.5 are never consulted, even though I believed both were doing something. The user and project model fields happen to name the same Opus 5 as a pin, so they do not stand out, but they lose on rank too. And one of the winning candidates retires in eleven days. Because warnings were printed, the exit code is 1.
After removing ANTHROPIC_MODEL from the shell profile and from the project's env block:
env var rank 5 claude-sonnet-5-5
└ ANTHROPIC_DEFAULT_MODEL — used only when no settings file sets model
user settings rank 4 claude-opus-5
└ /home/me/.claude/settings.json — model in a settings file
project settings rank 3 claude-opus-5
└ /work/proj/.claude/settings.json — model in a settings file
local settings rank 2 claude-haiku-4-5-20251001
└ /work/proj/.claude/settings.local.json — model in a settings file
shell profile rank - claude-sonnet-5-5
└ /home/me/.bash_profile:1 — exports ANTHROPIC_DEFAULT_MODEL in every new shell
→ wins at startup: claude-haiku-4-5-20251001 (/work/proj/.claude/settings.local.json)
never consulted: claude-opus-5, claude-sonnet-5-5Even with the pins gone, ANTHROPIC_DEFAULT_MODEL is still not used. The local settings model wins instead. This is the rank-four trap from the top of the post, and the place I tripped the second time. Only after removing model from all three settings files does the new variable finally take over:
env var rank 5 claude-sonnet-5-5
└ ANTHROPIC_DEFAULT_MODEL — used only when no settings file sets model
shell profile rank - claude-sonnet-5-5
└ /home/me/.bash_profile:1 — exports ANTHROPIC_DEFAULT_MODEL in every new shell
→ wins at startup: claude-sonnet-5-5 (ANTHROPIC_DEFAULT_MODEL)The script answers two questions: what is set, and which entry should win under the official order. It cannot see --model, an organization default, or managed settings. The final word is still /status inside a running session, and I find it safer to keep the listing and the measurement separate.
November 30 and the pins still sitting in your config
On the official model deprecations page, claude-sonnet-4-5-20250929 retires on November 30, 2026, with claude-sonnet-5-5 listed as the replacement (checked November 2026). The same page states that the undated claude-sonnet-4-5 is part of that retirement.
After that date, any environment that still pins this ID through ANTHROPIC_MODEL or a settings file will start normally and then fail on the first request. The docs say Claude Code shows a startup warning for models with a scheduled retirement date, but nobody reads that warning in an unattended job.
Using an alias such as sonnet or opus instead of a pinned ID makes this kind of leftover much less likely. I wrote up why the undated ID falls under the same deadline in Does an undated claude-sonnet-4-5 escape the November 30 retirement?.
Where I ended up putting things
Working on iOS and Android apps side by side as an indie developer, I want different models for different repositories. A project that is mostly reading existing code and one where I build a screen from nothing do not always call for the same model.
At first I set ANTHROPIC_DEFAULT_MODEL as my everyday default and planned to adjust with /model as needed. It did not go well. From the day I first pressed Enter in the picker, the default had been losing silently. I only noticed after I rewrote the script to print ranks.
Here is the line I draw now:
- No model settings in shell profiles at all. Nothing that takes effect where I cannot see it
- My everyday model is saved with
/modeland Enter. It lands in the user settingsmodel, which is a file I can read - Per-project differences go in
.claude/settings.jsonasmodel. Visible to me six months from now ANTHROPIC_DEFAULT_MODELonly where no settings file exists. A freshly rebuilt container, or a throwaway runtime with no home directory- Pins live inside a single command.
claude --model sonnet -p "...", orsin the picker for this session only
Pins belong to a command; defaults belong to a file. Pinning is a useful tool, but the moment you give it a long life it becomes a setting you will forget. Attaching it to the command I run, instead of a profile, has almost eliminated these hunts.
Three checks after you change anything
First, open a new shell and run env | grep ANTHROPIC. The shell you edited from still has the old values, so always check in a fresh one.
Second, start claude and look at the active model in /status. If you rely on ANTHROPIC_DEFAULT_MODEL, also confirm that the Default row in /model says "Set by ANTHROPIC_DEFAULT_MODEL." When the listing and the measurement agree, the setup is behaving the way you think.
Third, put the script somewhere its exit code matters. I run it before unattended jobs and stop the job if any warning appears. If you want a record of each model switch, see two hooks that record every model switch; if a typo in a settings key worries you, a one-letter typo in settings.json is ignored without a warning covers that.
The first step I would suggest today is a single search: grep -rn 'ANTHROPIC_MODEL\|ANTHROPIC_DEFAULT_MODEL\|sonnet-4-5' ~/.zshrc ~/.zprofile ~/.bashrc ~/.bash_profile ~/.profile ~/.claude/settings.json. If nothing comes back, at least there is no invisible pin. If something does, that line may be what is actually choosing your model right now.