Update Claude Code · Mac Install Guide · 2026

Updating Claude Code on macOS requires matching your upgrade command directly to your original install method: run claude update for native installs or brew upgrade --cask claude-code for Homebrew. If your version string stays frozen after running an update, you have multiple conflicting binaries sitting on your $PATH and the older binary is intercepting your shell commands.

Anthropic ships iterative CLI patches quickly. Following this Update Claude Code · Mac Install Guide · 2026 playbook will keep your local developer environment clean, avoid broken global permissions, and verify that your terminal tools receive the latest flags and features.

$ which -a claude
/opt/homebrew/bin/claude
~/.local/bin/claude # Conflict: multiple binaries detected

Identify your active install method before upgrading

You cannot run the right upgrade command until you verify which binary your shell currently resolves. Different installation methods store their binaries in completely separate macOS directories, and attempting to upgrade a Homebrew build using global npm commands will only corrupt your environment.

Run this to inspect your active version and find every installed binary:

$ claude --version
$ which -a claude

If which -a claude returns a single path like /opt/homebrew/bin/claude or ~/.local/bin/claude, your system is clean. If it returns multiple lines, you have multiple installs fighting for priority. The first entry in the output is the binary your shell executes when you type claude.

For a full internal diagnostic of your installation health, run:

$ claude doctor

claude doctor prints your installation method, Node runtime status, shell configuration files, write permissions, and the status of your last background update check. Take note of whether it reports a native, Homebrew, or npm environment.

--- Claude Code Doctor ---
Installation Type: Homebrew Cask
Binary Path: /opt/homebrew/bin/claude
Update Check: Passed (Up to date)
Settings File: ~/.claude/settings.json

Upgrade native and Homebrew installations

Native installs update automatically in the background on startup, while Homebrew installations require manual package manager upgrades unless you export an explicit auto-update environment variable.

If you installed Claude Code via the native installer, force an immediate update check by running:

$ claude update

The CLI checks Anthropic's distribution endpoints, pulls down the latest binary, and swaps it in place. If it finds no new version, it prints that you are already on the current release.

If you installed via Homebrew, manage the binary directly through brew:

$ brew upgrade --cask claude-code

If you track the preview channel using the latest cask, run this instead:

$ brew upgrade --cask claude-code@latest

Homebrew casks do not auto-update on their own. If you want Homebrew installs to check for updates automatically every time you launch a session, add this export to your shell configuration (~/.zshrc or ~/.zprofile):

export CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1

Avoid installing or updating Claude Code through npm (npm install -g @anthropic-ai/claude-code). Global npm updates require loose directory permissions, create unnecessary Node dependencies, and frequently fail during background auto-updates because macOS denies root directory write access. If you currently have an npm install, uninstall it and switch to the native installer or the Homebrew cask.

Resolve the frozen version bug caused by duplicate installs

When claude --version shows an outdated version immediately after running a successful update, an older orphaned binary is sitting higher on your $PATH. The updater modified one binary, but your shell is executing a different, abandoned binary.

To fix this, check all three common binary locations manually:

$ ls -la ~/.local/bin/claude
$ ls -la ~/.claude/local/
$ npm -g ls @anthropic-ai/claude-code 2>/dev/null

Decide which single install method you want to keep. Homebrew is standard for macOS power users, while the native installer offers zero-configuration background updating. Once you pick one, delete the competing alternatives.

To strip an npm global install:

$ npm uninstall -g @anthropic-ai/claude-code

To delete legacy local installs from older versions:

$ rm -rf ~/.claude/local

To remove an unwanted native binary:

$ rm -rf ~/.local/bin/claude

To remove an unwanted Homebrew cask:

$ brew uninstall --cask claude-code

After removing the duplicates, restart your terminal application or reload your shell environment:

$ exec zsh
$ which -a claude

Verify that which -a claude returns exactly one clean line. Run claude --version to confirm your active shell points directly to the updated release.

Configure release channels and version pinning in settings.json

You can control how and when Claude Code updates by editing your local configuration file or toggling options inside an active session.

To adjust these settings interactively, launch Claude Code and run the config slash command:

/config

Select Auto-update channel from the interactive menu to switch between latest and stable. The latest channel receives new features and patches immediately upon release. The stable channel runs roughly a week behind to prevent unexpected CLI regressions during critical work.

You can also set these values directly in ~/.claude/settings.json:

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "1.2.0",
  "env": {
    "DISABLE_AUTOUPDATER": "0"
  }
}

Key configuration flags:

• autoUpdatesChannel: Accepts "latest" or "stable". Controls which release ring your binary tracks.
• minimumVersion: Defines a version floor. If an environment issues a downgrade or attempts to run an outdated binary, the CLI halts execution.
• DISABLE_AUTOUPDATER: Setting this to "1" inside the env block stops background update checks while still allowing manual updates via claude update or brew upgrade.
• DISABLE_UPDATES: Setting this to "1" locks the environment completely and prevents all update attempts.

Verify updated slash commands and diagnostic tools

Recent versions of Claude Code introduce updated slash commands that give you direct visibility into context consumption and operational costs.

After updating, start a new terminal session and run /usage:

/usage

Earlier releases returned total token counts as a single unformatted integer. Updated builds display a categorized breakdown dividing token consumption across code context, reasoning tokens, system prompts, and tool output. This breakdown helps identify which specific files or prompt iterations are consuming your context budget.

--- Session Usage Breakdown ---
Total Input Tokens:     42,150
  - System Prompts:      6,200
  - Workspace Context:  28,400
  - Terminal Tool I/O:   7,550
Total Output Tokens:     3,820
Estimated Cost:         $0.24

Combine /usage with the /doctor command inside your active session to monitor runtime memory pressure, latency spikes to the Anthropic API, and active model capabilities. If a newly updated feature fails to show up, verify that your API key tier has access to the underlying model powering that command.

Feed pixel-accurate UI context into Claude Code terminal sessions

A clean terminal agent matters most when you are actively modifying frontend components and iterating on application state.

Claude Code edits files quickly when it knows the exact file paths and DOM context. But describing visual bugs using pure terminal text wastes tokens and causes unnecessary back-and-forth edits. Instead of typing vague descriptions like "fix the padding on the second button in the header," pass structured component data directly to the agent.

Using markagent, you can click any element in your browser via Cmd+Shift+. to extract the exact React component name, source file path, DOM hierarchy, and viewport layout. It copies a markdown prompt formatted for Claude Code straight to your clipboard.

<!-- Markagent context dropped into Claude Code -->
Fix visual regression on navigation item:
- Target File: `src/components/Header/NavButton.tsx`
- Component: `<NavButton active={true} />`
- Selector: `header > nav > button.btn-primary`
- Error: Active state background color does not meet contrast standards

Paste that structured markdown straight into your updated Claude Code terminal prompt. The agent reads the exact source file path, makes the target edit in your codebase, and reports back the diff without hallucinating surrounding styles.

Run claude doctor after any macOS migration to keep your environment healthy. Keep your $PATH stripped to a single binary, configure your update channel, and ship code faster.