Claude Code reference - versions, channels, and upgrades

The Claude Code reference section covers what changes under a working setup: which version and release channel is installed, what each release removed or changed, how to upgrade safely, and which features are still previews. On 2026-10-17 the latest channel is 2.1.302 and stable is 2.1.292. Both default to Claude Opus 5.5, and they differ in which changes they carry: everything from 2.1.293 on is latest-only.

This hub is for the developer who owns their own install and the tech lead who owns the team’s .claude/settings.json and CI jobs. A teammate says --model haiku now starts Claude Haiku 5.5. On your machine it still starts Haiku 4.5, and neither of you changed a setting. You are on different channels: the alias moved in 2.1.293, which only latest has, and nothing told you.

What this Claude Code reference section gives you

• A two-minute check of your version, channel, and default model
• A map from the question you have to the reference page that answers it
• Two copy-paste prompts that turn release notes into a list of what affects your repository
• A short smoke test that proves an update did not break auth, model access, or JSON output

Which Claude Code version and channel are you running?

Run these checks before you debug a missing command or a changed default.

1. Print the installed version in a terminal:

   claude --version

2. Compare it with what each channel currently offers:

   npm view @anthropic-ai/claude-code dist-tags

   On 2026-10-17 this lists latest and next at 2.1.302 and stable at 2.1.292.

3. Check the installation without starting a session:

   claude doctor

   claude doctor also reads the settings files in the current directory. Inside a session, /doctor runs a fuller checkup that can fix issues.

4. In a session, run /model to see the model you actually get. Run /release-notes to open the version picker for release notes.

	latest channel	stable channel
Version on 2026-10-17	2.1.302	2.1.292, “typically about one week old” according to Anthropic’s setup guide, and it skips releases with major regressions
You are on it when	you used the native installer or npm with defaults, or Homebrew cask claude-code@latest	you set autoUpdatesChannel: "stable", installed with bash -s stable, or use Homebrew cask claude-code
Default model	Claude Opus 5.5 on every paid plan and the API (needs 2.1.280 or later)	the same, because 2.1.292 is newer than 2.1.280
Model aliases on the Anthropic API	sonnet is Claude Sonnet 5.5 (from 2.1.284); haiku is Claude Haiku 5.5 (from 2.1.293)	sonnet is Claude Sonnet 5.5; haiku resolves as it did before 2.1.293, to Haiku 4.5, because Haiku 5.5 needs 2.1.293
Changes from 2.1.293 on, such as the haiku alias for Haiku 5.5 and the hook onFailure field	included	not yet: stable is 2.1.292
Starting permission mode, interactive sessions	auto on every plan and provider (needs 2.1.283), unless the model does not support it	the same, because 2.1.292 is newer than 2.1.283

claude -p and the Agent SDK start in Manual on both channels, except on third-party providers or with telemetry off, where they start in auto mode from 2.1.285. The per-plan and per-provider defaults, prices, and aliases live on the models hub; Microsoft Foundry differs from both columns.

Which reference page answers your question?

Your question	Page
What changed in version X, and what did it break?	Claude Code version history
How do I upgrade one repository’s CI safely, or pin a team to one version?	Claude Code version history, sections on CI upgrades and team pinning
How do I roll an upgrade out to a fleet, and roll it back?	Claude Code upgrade procedures
Is this feature a research preview, beta, or experimental, and how do I turn it off?	Beta features and research previews
Which command or settings key does what, across tools?	Command reference and configuration reference

Copy-paste prompt: what the gap to latest means for this repository

Run `claude --version` and `npm view @anthropic-ai/claude-code dist-tags`
and tell me which channel I am on and how many releases I am behind latest.
Fetch https://code.claude.com/docs/en/changelog.md and read every entry after
my version. Then read .claude/settings.json, .claude/agents/, .claude/skills/,
CLAUDE.md, AGENTS.md and .github/workflows in this repository.
List only the changes that affect what this repository uses: removed commands
or settings, changed defaults (model, permission mode, instruction files),
and hook or MCP behaviour. For each, quote the changelog line with its
version and show the file:line in this repository it touches.
Do not edit files. Do not invent versions or settings keys.

Copy-paste prompt: find where the team's Claude Code version floats

Find every place this repository installs or runs Claude Code: CI workflows,
Dockerfiles, devcontainer config, Makefiles, shell scripts and setup docs.
For each one, report: file:line, how it installs (native, npm, Homebrew,
image), whether the version is pinned to an exact number, whether
DISABLE_AUTOUPDATER or DISABLE_UPDATES is set, and whether the claude
invocation passes --model. Flag every place where the version or the model
can change without a commit. End with a table and a one-line fix per row.
Do not edit files.

Both prompts ask for a file and line or a quoted changelog entry behind every finding, so you check each claim against its source instead of trusting the summary.

How do you prove an update did not break your setup?

You do not need to read the agent’s transcript. After any version change, run a bounded smoke test whose pass signal is one word:

claude doctor
claude -p --output-format json --max-budget-usd 0.50 "Reply with the single word OK." | jq -r '.result'

The second command (needs jq; without it, check that the JSON’s result field is OK) proves authentication, model access, and JSON output in one call, and cannot spend more than $0.50. Then trigger one hook on a fixture file and check its side effect, and re-run one automation that uses --output-format json against a known input: same keys, same verdict. In CI, the engineer who owns the pipeline config approves the version bump only after these pass. The full seven-step routine is in the version history’s upgrade section.

What goes wrong with Claude Code versions, and how do you recover?

• A shared command is “unknown”. Your build predates it, or you are on stable. Run claude update, or claude install latest for the newest build, and set autoUpdatesChannel: "latest" so auto-updates follow it. claude install 2.1.296 installs an exact version.
• Homebrew never updates. Neither cask auto-updates by default. Run brew upgrade --cask claude-code (or claude-code@latest, whichever you installed).
• Background sessions misbehave after an update. They keep running the old binary. Run claude respawn --all so they pick up the current version.
• CI results shifted with no commit. The default model moved to Opus 5.5 in 2.1.280 (both channels since stable reached 2.1.287), the sonnet alias to Sonnet 5.5 in 2.1.284, and the haiku alias to Haiku 5.5 in 2.1.293 (latest only). Pin the exact Claude Code version and pass --model in every CI invocation, then re-run your evals before you move either pin.
• A pinned machine updated anyway. DISABLE_AUTOUPDATER=1 stops only the background check, so a person can still run claude update. DISABLE_UPDATES also blocks claude update and claude install; use it only when your own channel distributes Claude Code.

Checked against Claude Code 2.1.283 (claude --help, claude doctor --help, claude install --help, claude respawn --help) on 2026-09-26. The version, channel and default-model statements above were checked again on 2026-10-12 against npm, the native installer’s channel pointers, the Homebrew casks and Claude Code’s model configuration page, with the installed CLI at 2.1.296. The channel versions were checked again on 2026-10-17 against npm, the native installer’s channel pointers and the Homebrew casks.

Where to go next with Claude Code versions

Claude Code version history Releases, breaking changes, the CI upgrade routine, and team pinning.

Claude Code upgrade procedures Fleet rollouts, staged waves, and rollback.

Beta features and research previews What is still a preview and how to trial it safely.

Install Claude Code The prerequisite: native, npm, Homebrew, and package-manager installs.

For errors that are not version-related, see Claude Code troubleshooting. The sibling reference sections for the other tools are Codex reference and Cursor reference.