Claude Code Upgrade Procedures

Upgrading Claude Code requires careful planning and execution, especially in team or enterprise environments. This guide provides comprehensive procedures for safe, reliable upgrades with minimal disruption to your workflow.

Claude Opus 4.7 Migration (April 2026)

Breaking changes in Claude Opus 4.7

Opus 4.7 (claude-opus-4-7, released 2026-04-16) introduces four Messages-API-level breaking changes. Claude Code hides most of this from you, but if you use Opus 4.7 via the SDK or your own API clients — or via LLM gateways like LiteLLM — you must update your request shapes. Claude Managed Agents users are unaffected.

1. Extended thinking budgets removed

thinking: {"type": "enabled", "budget_tokens": N} now returns 400. Adaptive thinking is the only thinking-on mode, and it’s off by default on Opus 4.7.

# Before (Opus 4.6)
thinking = {"type": "enabled", "budget_tokens": 32000}

# After (Opus 4.7)
thinking = {"type": "adaptive"}
output_config = {"effort": "high"}  # or "xhigh" for deepest reasoning

2. Sampling parameters removed

Setting temperature, top_p, or top_k to a non-default value returns 400. Just omit them — prompt for determinism instead (note: temperature=0 never guaranteed identical output).

# Before
response = client.messages.create(model="claude-opus-4-6", temperature=0, ...)

# After — omit sampling params
response = client.messages.create(model="claude-opus-4-7", ...)

3. Thinking content omitted by default

Thinking blocks are still emitted but their thinking field is empty unless you opt in. This is a silent change — set display to restore visible reasoning output.

thinking = {
    "type": "adaptive",
    "display": "summarized",  # or "omitted" (default)
}

UX impact: if your product streams reasoning to users, the new default looks like a long pause before output begins. Use "summarized" to restore visible progress during thinking.

4. New tokenizer (~1.0–1.35x token usage)

Opus 4.7 uses a new tokenizer. Expect anywhere from same to ~35% more tokens compared to Opus 4.6 depending on workload shape. /v1/messages/count_tokens will return different numbers for the same input. Bump max_tokens for headroom — including compaction triggers in Claude Code.

Opus 4.7 ships with the full 1M context at standard API pricing (no long-context premium). In Claude Code, versions before v2.1.117 computed context against a 200K window even when running Opus 4.7, causing inflated /context percentages and early autocompact. Update Claude Code to 2.1.117+ before pinning Opus 4.7 to get the fix.

Task budgets (beta)

Opus 4.7 adds an optional task_budget as a soft cap on total tokens across a full agentic loop (including thinking, tool calls, tool results, final output). Unlike max_tokens, the model sees the running countdown and self-moderates.

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000},
    },
    messages=[{"role": "user", "content": "Refactor the auth module."}],
    betas=["task-budgets-2026-03-13"],
)

Minimum value is 20k tokens. Skip it for open-ended work where quality matters more than token spend.

Behavior changes (not API-breaking, but worth knowing)

• More literal instruction following — remove “double-check the X before returning” style scaffolding; Opus 4.7 no longer generalizes across items you didn’t ask about.
• Response length calibrates to task complexity — expect leaner output on simple asks.
• Fewer tool calls by default, uses reasoning more — raise effort to increase tool usage.
• More direct, opinionated tone — less validation-forward, fewer emoji.
• Fewer subagents spawned by default — steerable through prompting.

Claude Sonnet 4 / Opus 4 deprecation

The legacy Claude Sonnet 4 (claude-sonnet-4-20250514) and Claude Opus 4 (claude-opus-4-20250514) models retire 2026-06-15. Migrate to claude-sonnet-4-6 and claude-opus-4-7 respectively before that date. See Anthropic’s model deprecations page for details.

Understanding Upgrade Paths

Auto-Updates (Default)

Seamless background updates with zero downtime - recommended for most users

Manual Updates

Full control over timing and testing - ideal for teams and enterprises

Version Pinning

Lock to specific versions for stability - required in regulated environments

Rollback Ready

Always maintain ability to revert - critical for production environments

Pre-Upgrade Checklist

Before any upgrade, ensure you’re prepared:

1. Check Current Version

   claude --version
   claude doctor  # More detailed diagnostics

2. Review Release Notes

   # Within Claude Code
   /release-notes
   
   # Or check GitHub
   # github.com/anthropics/claude-code/releases

3. Backup Critical Configurations

   # Backup your configurations
   cp -r ~/.claude ~/.claude.backup.$(date +%Y%m%d)
   cp -r .claude .claude.backup.$(date +%Y%m%d)

4. Test in Non-Critical Environment

   • Use a sandbox project first
   • Verify core workflows still function
   • Check custom commands and hooks

5. Notify Team Members

   • Communicate upgrade schedule
   • Share any breaking changes
   • Coordinate timing for minimal disruption

Upgrade Procedures by Installation Type

NPM Global Installation

Standard Upgrade

# Check for updates
npm outdated -g @anthropic-ai/claude-code

# Perform upgrade
npm update -g @anthropic-ai/claude-code

# Verify upgrade
claude --version

Clean Install

# Sometimes needed for major version jumps
npm uninstall -g @anthropic-ai/claude-code
npm cache clean --force
npm install -g @anthropic-ai/claude-code

Specific Version

# Pin to specific version
npm install -g @anthropic-ai/claude-code@1.0.54

# Verify exact version
npm list -g @anthropic-ai/claude-code

Tip

Permission Issues? If npm upgrade fails with permission errors, consider migrating to local installation:

claude install

Local Installation (Recommended)

The local installation method avoids permission issues and provides smoother updates:

# If you haven't migrated yet
claude install

# Updates happen automatically or manually
claude update

# Check installation location
which claude  # Should show ~/.claude/local/claude

Native Binary Installation (Alpha)

Update Binary

# From existing installation
claude install

# Or fresh install
curl -fsSL claude.ai/install.sh | bash

Platform Notes

• macOS: Universal binary, works on Intel and Apple Silicon
• Linux: Automatic architecture detection
• Windows: Use WSL for binary installation

Handling Breaking Changes

Example: Bedrock ARN Format Change (v0.2.125)

When upgrading across breaking changes, follow this pattern:

1. Identify the Change

   • Old format: arn:aws:bedrock:region::foundation-model/model%2Fversion
   • New format: arn:aws:bedrock:region::foundation-model/model/version

2. Update Configuration

   # Before upgrade, update environment variables
   export ANTHROPIC_MODEL="arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-opus-4-7"
   # Note: No %2F, use literal /

3. Test Configuration

   # Verify configuration works
   claude doctor

4. Proceed with Upgrade

   claude update

Common Breaking Change Categories

Configuration Format

JSON structure changes, new required fields, deprecated options

API Changes

SDK field renames (e.g., total_cost → total_cost_usd)

Tool Renames

Built-in tools get clearer names (e.g., LSTool → LS)

Command Changes

Slash commands or flags modified or deprecated

Enterprise Upgrade Strategy

Version Control and Testing

• Directoryinfrastructure/

  • Directoryclaude-code/

    • versions.json (approved versions)
    • Directorytest-suite/ (upgrade validation)

      • …
    • Directoryrollback-scripts/

      • …
• Directorydocumentation/

  • upgrade-log.md
  • known-issues.md

Staged Rollout Process

1. Development Environment

   • Test with volunteer developers
   • Run for 1-2 days
   • Collect feedback

2. Staging Environment

   • Broader testing group
   • Full workflow validation
   • Performance benchmarking

3. Production Rollout

   • Communicate via team channels
   • Staggered by team/region
   • Monitor for issues

4. Post-Upgrade Review

   • Gather team feedback
   • Document any issues
   • Update procedures

Enterprise Configuration Management

# Disable auto-updates company-wide
export DISABLE_AUTOUPDATER=1

# Version pinning in package.json
{
  "devDependencies": {
    "@anthropic-ai/claude-code": "1.0.54"
  }
}

# Automated deployment script
#!/bin/bash
APPROVED_VERSION="1.0.54"
CURRENT_VERSION=$(claude --version | grep -oE '[0-9]+\.[0-9]+\.[0-9]+')

if [ "$CURRENT_VERSION" != "$APPROVED_VERSION" ]; then
  npm install -g @anthropic-ai/claude-code@$APPROVED_VERSION
fi

Rollback Procedures

When an upgrade causes issues, quick rollback is essential:

Immediate Rollback

NPM Method

# Rollback to previous version
npm install -g @anthropic-ai/claude-code@1.0.53

# Restore configuration backup
rm -rf ~/.claude
mv ~/.claude.backup.20250716 ~/.claude

Local Install

# Local installations maintain version history
cd ~/.claude/versions

# List available versions
ls -la

# Switch to previous version
ln -sf 1.0.53 current

Rollback Checklist

• ☐ Stop all running Claude Code instances
• ☐ Restore previous version
• ☐ Restore configuration backups
• ☐ Clear any corrupted cache/state
• ☐ Verify functionality
• ☐ Document issues for bug report

Post-Upgrade Verification

After any upgrade, verify critical functionality:

1. Basic Functionality

   # Check version and diagnostics
   claude --version
   claude doctor
   
   # Test basic interaction
   claude "Hello, are you working correctly?"

2. Configuration Integrity

   # Verify settings preserved
   cat ~/.claude/settings.json
   
   # Check custom commands
   ls .claude/commands/

3. Tool Functionality

   # Test file operations
   claude "List files in current directory"
   
   # Test MCP servers
   /mcp list

4. Performance Check

   • Response time
   • Memory usage
   • Context handling

Troubleshooting Common Upgrade Issues

Configuration Corruption

Caution

If Claude Code fails to start after upgrade, configuration corruption is often the cause.

# Diagnose configuration issues
claude doctor

# Reset to defaults if needed
mv ~/.claude/config.json ~/.claude/config.json.backup
claude # Will recreate with defaults

Permission Errors

# NPM permission issues
sudo npm install -g @anthropic-ai/claude-code  # Not recommended

# Better solution: migrate to local
claude install

Version Conflicts

# Check for multiple installations
which -a claude
type -a claude

# Remove duplicates
npm uninstall -g @anthropic-ai/claude-code
# Then reinstall

MCP Server Compatibility

After major upgrades, MCP servers may need updates:

# Check MCP server status
/mcp list

# To update an MCP server, remove and re-add it
claude mcp remove <server-name>
claude mcp add <server-name> <command> [args...]

Best Practices Summary

Always Backup

Configuration and custom commands before any upgrade

Test First

In isolated environment before team-wide rollout

Read Release Notes

Understand changes and potential impacts

Coordinate Teams

Synchronize upgrades to avoid version mismatches

Monitor Post-Upgrade

Watch for performance changes or new issues

Document Everything

Keep upgrade logs for future reference

Emergency Contacts

If critical issues arise during upgrade:

1. GitHub Issues: Report bugs with version details
2. Community Forums: Check if others experiencing same issue
3. Rollback First: Don’t try to fix forward in production
4. Document Thoroughly: Help others avoid same problem

Tip

Remember: The rapid development of Claude Code means frequent updates with valuable improvements. A well-planned upgrade process lets you benefit from new features while maintaining stability.