Migrating from Claude 4.6 to 4.7: The 7-Step Guide

Claude Opus 4.7 hit general availability on April 16, 2026. Same price as 4.6, +13 points on SWE-Bench Verified (87.6%), 3× higher vision resolution, a new tokenizer, file-system memory, and the 1M context window opens by default.

The official Anthropic guidance is "drop-in compatible" — and for most code, that's true. But we run 36 production AI apps on Claude, and the migration broke three of them. The fixes were simple once we knew where to look. This guide is the playbook in the order we'd run it again.

Step 1: Update the model identifier

Change the model name everywhere it appears:

# Before
model = "claude-opus-4-6"

# After
model = "claude-opus-4-7"

Sounds trivial. Audit thoroughly anyway — model IDs commonly hide in:

• .env files and per-environment overrides
• Hard-coded strings in fallback / retry logic
• Config YAML or TOML for orchestration tools
• Prompt templates that reference the model name in the system prompt
• Logging / metrics tags (don't forget — your dashboards still say "4.6")

Do this before anything else. The rest of the migration assumes you're already on 4.7.

Step 2: Re-audit your token budgets

Opus 4.7 ships a new tokenizer. The Anthropic team has been measured about this — the average change is ~5%, but it's not uniform. English prose shifts a few percent. Code with heavy punctuation can shift more. Non-Latin scripts shift quite a bit in either direction.

What this breaks:

• Hard token caps in your prompt templates. If you had maxTokens: 8000 hand-tuned for 4.6's tokenizer, it's no longer the same cutoff.
• Cache invalidation. Caches keyed by token count or by exact string match may invalidate when re-encoded.
• Cost forecasts. Re-run your projected spend with the new tokenizer numbers before scaling.

The fix: re-tokenize a sample of your real production prompts and recompute the caps. Anthropic ships a tokenizer endpoint — use it once per template, not at runtime.

Step 3: Enable the 1M context window

The 1M context window is available via beta header. Add it explicitly so you can rollback if you hit issues:

headers = {
  "anthropic-beta": "context-1m-2026-04-16"
}

# And bump your max_tokens if you were capping at 128k or below
max_tokens = 128000  # 128k output cap on Opus 4.7

For caching the 1M prefix to keep costs sane, see our 1M Context Window Guide. Short version: cache the static prefix first, keep the variable tail tiny, batch queries inside the 5-minute TTL.

Step 4: Wire up the file-system memory tool

This is the upgrade nobody talks about enough. Opus 4.7 ships with substantially better behavior around file-system-based memory — scratchpads, note files, structured memory stores that the agent maintains across turns. Earlier models would forget to write notes or write them inconsistently. 4.7 actually maintains them.

Wire it up:

tools = [
  {
    "type": "memory",
    "name": "scratchpad",
    "directory": "/var/agent-memory/{agent_id}/",
    "max_size_mb": 10
  },
  # ... your other tools
]

The agent will now create files like plan.md, blockers.md, customer-context.md on its own as it works. On the next invocation, it reads them back. This is the foundation underneath the new "dreaming" feature in Managed Agents — covered in detail in our Dreaming Memory guide.

Step 5: Bump vision resolution

Max image resolution jumped from 1568px (1.15MP) on 4.6 to 2576px (3.75MP) on 4.7. If you were downsampling images to fit the 4.6 cap, you can stop. The model now reads:

• Full-page PDF screenshots without re-rendering at 200% zoom
• Dense dashboards (Grafana, Datadog) without losing the small-text annotations
• Architecture diagrams with readable boxes and arrows
• Photos with small but important text (whiteboards, receipts, ID cards)

Update your image preprocessing pipeline:

# Before — 4.6 cap
MAX_DIMENSION = 1568

# After — 4.7 cap
MAX_DIMENSION = 2576

Worth noting: high-res images cost more (more tokens). If you're processing a lot of images, profile cost before turning the cap up everywhere.

Step 6: Test Fast Mode

Fast Mode (research preview) now supports Opus 4.7. Same brain, faster output token generation, premium pricing. Add the header to test it on latency-sensitive paths:

headers = {
  "anthropic-beta": "fast-mode-2026-02-01"
}

body = {
  "model": "claude-opus-4-7",
  "speed": "fast",
  # ...
}

Where it shines: chat UIs, code completion, anything user-facing where the human is staring at a spinner. Where it doesn't help: batch jobs, async agents, cron'd workflows. The latency wins don't matter when nobody is waiting.

Note: Fast Mode currently produces slightly shorter reasoning traces. We've seen output quality match the standard mode on day-to-day tasks but degrade slightly on extremely complex multi-step problems. Test before you flip it for everything.

Step 7: Audit for the 3 known gotchas

These three got us:

Gotcha 1: Memory tool overwrites

The agent will overwrite its own memory files without explicit permission. If you have a workflow where the previous notes are critical (compliance logs, audit trails), set the memory tool to append-only or use a separate write-once log file the agent doesn't touch.

Gotcha 2: Cache keys silently changed

If you're using Anthropic's prompt cache and you upgraded models, your cache keys are now different. The first call after migration will be a full uncached call. Budget for that — for our biggest cache (a 700k prefix), it added about $5 per agent in cold-start cost on day one.

Gotcha 3: Fast Mode + tools = unstable interplay

As of May 2026, Fast Mode and tool use are both in beta but interact in unexpected ways. Fast Mode sometimes truncates tool input arguments under high-throughput conditions. We saw it about 1 in 200 calls. If you're using both, retry on malformed tool calls or hold Fast Mode for tool-free paths until Anthropic ships a fix.

The takeaway

The 4.7 migration is mostly clean. The places it isn't are predictable: token budgets, cache keys, memory tool edge cases, Fast Mode + tools. Walk the seven steps, run your eval suite, watch the gotchas, and you'll be shipping on the new model by Friday.

If you want the migration kit we used internally — the eval suite skeleton, the tokenizer audit script, the memory tool templates with per-agent isolation built in — it's bundled into the Whole Farm alongside everything else. One payment, lifetime updates as Anthropic keeps shipping.