How to Update Claude Code (And What to Check Before You Do)

To update Claude Code, run claude update in your terminal. If you installed with Homebrew, use brew upgrade claude-code. If you used npm, run npm install -g @anthropic-ai/claude-code@latest. Verify with claude --version. Before you update a machine you actually work on, read the changelog and back up your ~/.claude folder. Anthropic ships fast and breaking changes happen. At Formaum, I update Claude Code on a stable schedule across client builds, and these are the checks that catch the breaks before they hit production.

The update command

The fastest path is the built-in command:

claude update

That works for the native installer (the one most people have if they installed in 2026). It checks the channel you're on, downloads the new binary, and swaps it in. Next time you start Claude Code, you're on the new version.

If you installed a different way, use the matching command:

# Homebrew stable cask
brew upgrade claude-code

# Homebrew latest cask
brew upgrade claude-code@latest

# WinGet on Windows
winget upgrade Anthropic.ClaudeCode

# npm global install
npm install -g @anthropic-ai/claude-code@latest

One note on npm: do not use npm update -g. It respects the semver range from your original install and often does not actually move you to the newest release. Use the explicit @latest form.

Then verify:

claude --version

When to update vs when to hold

The default advice online is "always be on the latest version." That's fine for a personal sandbox. It's not fine for a machine running client work.

I run Claude Code on two kinds of setups. My main workstation, where I ship production work for clients, and side machines I use for testing. The side machines stay on latest. The workstation runs on stable, which is about a week behind and skips releases with major regressions.

You set the channel in your settings.json:

{
  "autoUpdatesChannel": "stable"
}

Hold on updating when: you're mid-sprint on a client build, you have custom hooks or skills that depend on specific behaviour, or you saw a release note that mentions changes to MCP, settings schema, or the skills folder. Wait a week. Let other people find the bugs.

Read the changelog. Make it a habit.

This is the step most update guides skip. Before you update, open the changelog. Two minutes of reading saves an hour of debugging.

The official changelog lives at github.com/anthropics/claude-code/blob/main/CHANGELOG.md. Scan for anything that mentions: settings schema, MCP, skills, hooks, sandboxing, permissions, or anything labelled "breaking."

If you see one of those, slow down. Read the full entry. Decide if it affects you.

Post-update verification

After the update, run these in order:

claude --version
claude doctor

claude doctor is the diagnostic. It checks your install, your settings file, your MCP servers, and your auth. If something broke in the update, this is where you'll see it first.

Then open Claude Code in a project you know well. Run a small task that exercises your normal setup. If you use MCP servers, check they all connected. If you use skills, trigger one. If you use hooks, watch for them firing.

Common breaks after an update

These are the ones I've actually hit, not theoretical ones.

MCP version mismatch. An MCP server that was happy on the old version of Claude Code throws errors on the new one, usually because the MCP protocol version moved. Fix: update the MCP server too. claude mcp list will show the status. If a server is failing, check its repo for a newer release.

settings.json schema change. Anthropic occasionally moves or renames fields. The classic example is when permissions moved structure in early 2026. Your old settings still parse but stop being honoured. Fix: compare your settings against the current docs at code.claude.com/docs/en/settings and update the keys.

Skills folder structure. The skills feature has evolved. Folder layout, frontmatter fields, and trigger format have all shifted. If a skill suddenly stops triggering, open one that ships with the harness and compare structure.

Hooks not firing. Hook config format changed at least once in 2026. If your onStop or onSessionStart hooks go silent, check the hooks section in the docs and rewrite the entry.

Permissions reset. A new permission category gets added and your allowlist no longer covers it. You'll see prompts for tools that used to run silently. Add the new permission to settings.json and you're back.

How to roll back

You can pin Claude Code to any specific version. The native installer accepts a version number:

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89

# npm
npm install -g @anthropic-ai/claude-code@2.1.89

Pick a version from the GitHub changelog. The format is X.Y.Z. Anthropic also exposes a minimumVersion setting that establishes a floor, so background auto-updates won't quietly move you down again:

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.100"
}

This is the safety net I rely on. I pin the floor to a version I've tested, then let auto-updates take me forward from there. If a future release is bad, I roll back without dropping below my known-good baseline.

Auto-update vs manual

Native installations auto-update by default. Homebrew, WinGet, apt, dnf, and apk do not.

Pros of auto-update: you stay current, security patches arrive without thinking about it, you don't drift months behind.

Cons: an update lands at the wrong moment and breaks a client demo, or you're debugging an issue and don't realise the binary moved underneath you.

My setup: auto-update on, channel set to stable, minimumVersion pinned, changelog scan once a week. That's the balance between "current enough" and "nothing surprises me."

If you need to fully disable auto-update on a machine, add this to settings.json:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

That stops the background check. claude update still works when you want to update manually.

One last thing

Back up ~/.claude before any major version jump. It's where your settings, skills, MCP config, and session state live. If an update corrupts something, you want a copy. A quick cp -r ~/.claude ~/.claude.bak-2026-05-29 takes one second and saves entire afternoons.

Updating Claude Code is mostly painless. But it runs in your client work, your terminal, and your build pipeline. Treat it the way you'd treat a Node version bump on production. A two-minute checklist beats a two-hour incident.

Genevieve Claire

Founder, Formaum — Claude Code Expert & Full-Stack AI Engineer

Builds bespoke AI automation systems for multi-location operations. Previously EA Sports FIFA ($7B franchise) and Film/TV VFX on Skyfall, Avengers, Game of Thrones. Based in Vancouver, BC.