How to Upgrade Claude Code to Opus 5 and Roll Back Safely

Update Claude Code with claude update, restart it, select Opus with /model opus, and confirm the active model with /status. Test the new model in a fresh session on one bounded task before changing a team-wide default. If the result regresses, switch that session back with /model claude-opus-4-8; you usually do not need to downgrade the Claude Code client.

Anthropic released Claude Opus 5 on July 24, 2026. It is available across Anthropic's platforms, uses the API model ID claude-opus-5, and keeps Opus 4.8's list price of $5 per million input tokens and $25 per million output tokens. Availability in Claude Code still depends on your account, organization policy, provider, gateway, and current client.

Before You Upgrade

You need:

• a working Claude Code installation and account;

• permission to use Opus models in your organization;

• a clean or recoverable repository for the test;

• one representative task with a result you can check;

• your current model, effort, and client version recorded.

From your shell, capture the client version:

claude --version

Then start Claude Code and run:

/status

Record the model, account, and provider shown. Do not infer the active model from a release announcement, subscription name, or a successful client update.

Step 1: Update the Claude Code Client

For Claude Code's native installer, run:

claude update
claude --version

Close existing Claude Code sessions and start a new one after the update. Native installations can update automatically in the background, but the new binary takes effect after restart.

If you installed Claude Code with Homebrew, WinGet, apt, dnf, or apk, follow the package-manager command in Anthropic's setup guide. Do not replace a managed installation with an unofficial npm @next command copied from a social post. Package-manager releases can lag the native installer, so a missing model immediately after launch may be a distribution delay rather than an account problem.

Expected result: claude --version succeeds and a newly started session opens normally.

Step 2: Select Opus 5 Explicitly

Inside the new session, open the model picker:

/model

Choose Opus 5 if it is listed. You can also select the Opus family alias:

/model opus

The opus alias resolves to the newest permitted Opus model. If you want a one-session launch from the shell, use:

claude --model opus

For an API-backed workflow that must pin the exact model, use claude-opus-5. A family alias is easier to maintain; an exact ID is easier to audit. Pick one deliberately.

Expected result: the picker accepts the model without substituting an organization-approved alternative.

Step 3: Verify What Is Actually Running

Run:

/status

Confirm that the active model is Opus 5. Anthropic documents /status and a configured status line as the two places to check the current model.

This verification matters because resumed sessions preserve the model saved in their transcript. Updating the client or changing a default does not necessarily change an old conversation. If a resumed session still shows Opus 4.8, either switch it explicitly or start a fresh session.

Also check the effort level. Opus 5 defaults to high effort in Claude Code and the Claude API. Do not assume an older effort setting remains the best cost and latency tradeoff: Anthropic recommends re-running an effort sweep because the levels were recalibrated.

Expected result: /status names Opus 5 and the intended effort level before you give the model a write task.

Step 4: Run a Small Acceptance Test

Start with a read-only task whose answer you can inspect:

Read the project README and the test command in package.json.
Return three verified facts with their file paths.
Do not edit files or run tests

Check that:

1. every fact exists at the cited path;

2. no file changed;

3. the response followed the requested length;

4. latency and usage are acceptable for this kind of task.

Then run one representative coding task on a disposable branch. Keep its scope narrow, run the same tests you would use in review, and compare the diff against a known-good baseline. A model launch benchmark is not a substitute for your repository's own acceptance criteria.

Opus 5 may write longer visible responses than earlier Opus models. If that hurts the workflow, ask for a target length directly. Lower effort can reduce thinking volume, but Anthropic says it does not reliably shorten the visible answer.

Step 5: Keep External Actions Bounded

A model change does not require reconnecting every integration or pasting provider credentials into a prompt. Keep the existing tool boundary, inspect the current Action schema, and test one read-only operation before enabling writes.

Give Claude Code this instruction:

Follow https://aident.ai/SETUP.md
Find one read-only Action for a connected service and inspect its current schema.
Show the exact operation and inputs before execution.
Run it once only after I approve. Do not request provider credentials

Expected result: one read-only Action completes with a reviewed input, while the provider secret stays outside the conversation and repository.

Step 6: Roll Back the Model Without Downgrading the Client

If Opus 5 produces a worse result, switch the active session back:

/model claude-opus-4-8

Verify the change:

/status

For a new one-off session:

claude --model claude-opus-4-8

This is a model rollback, not a client rollback. Keep the current Claude Code client unless the client itself has a confirmed regression. New clients contain model discovery, policy, and diagnostic changes that can be useful even when you choose an older model.

If your organization does not permit the exact Opus 4.8 ID, use /model and choose an allowed alternative. Do not bypass an organization allowlist with a custom gateway mapping.

Common Failure Modes

Opus 5 Does Not Appear in /model

Run claude update, restart Claude Code, and open a fresh session. If it is still missing, check account eligibility, organization restrictions, and provider or gateway model discovery. The picker reflects organization access on a new session, not necessarily in an already running one.

/status Still Shows Opus 4.8

You may have resumed an older transcript. Run /model opus in that session or start a fresh one with claude --model opus. Also check whether a project, user, or managed setting pins a model at startup.

The First Request Falls Back to Opus 4.8

Anthropic says some Opus 5 cybersecurity requests can fall back to Opus 4.8. Workspace context can trigger classification on the first request. Inspect the fallback notice rather than repeatedly retrying. For legitimate security work, follow Anthropic's documented fallback and verification guidance.

A Request Fails With Thinking Disabled

Opus 5 permits disabled thinking only at high effort or below. Combining disabled thinking with xhigh or max returns an error. Re-enable adaptive thinking or lower effort.

Cost or Latency Jumps

Re-test your real workload at medium, high, and the higher levels you actually need. Fast mode runs at about 2.5 times the default speed but costs twice the base price. Record tokens, wall time, acceptance-test results, and retries instead of comparing a single subjective response.

The Context Window Looks Smaller Than Expected

Anthropic documents a 1 million token context window for Opus 5 on the Claude API, but gateways and organization controls can affect what Claude Code can verify or expose. Treat /status, provider configuration, and your organization's policy as the source of truth for the active session.

Why This Process Works

The client update makes current model metadata available. Explicit selection removes ambiguity about aliases and defaults. /status verifies the runtime instead of trusting configuration intent. A bounded acceptance test separates model quality from client or integration problems. A session-level rollback restores a known model without discarding current client fixes.

For a broader agent migration, use How to Migrate from Claude Code to Codex Without Losing Your Setup. To shrink tool context before comparing models, read How to Reduce MCP Token Usage in Claude Code and Codex. For integration boundaries, see How to Connect Claude Code and Codex to Real-World Tools.

Use Aident Loadout to run one scoped read-only Action after the model change, then record whether the same schema, input, and expected result still pass.

Sources

• Introducing Claude Opus 5, Anthropic, July 24, 2026

• Claude model migration guide, Anthropic, accessed July 24, 2026

• Claude Code model configuration, Anthropic, accessed July 24, 2026

• Claude Code CLI reference, Anthropic, accessed July 24, 2026

• Claude Code setup and update guide, Anthropic, accessed July 24, 2026

• Claude Code issue: organization-ineligible Opus 5 default, opened July 24, 2026

• Claude Code issue: effort xhigh WebSearch failure, opened July 24, 2026

• Community question: Can you already use Opus 5 in Claude Code?, July 24, 2026

Refresh this guide when Anthropic changes Claude Code's model aliases, Opus 5 availability, effort behavior, context limits, fallback policy, update commands, or Opus 4.8 availability.