Claude Code /cd: Switch Directories, Preserve Prompt Cache, 3 Edge Cases (2026)

The single most asked-for Claude Code feature of 2026 just shipped quietly in v2.1.169, and most users still don’t know it preserves the prompt cache instead of nuking it.

If you’ve been exiting and restarting Claude Code every time you wanted to work in a git worktree or a sibling repo, the /cd command released on 2026-06-08 ends that ritual. It moves a session to a new working directory mid-flight without breaking the cached prefix — which on Claude Opus 4.8 (input $5/M, cache read $0.50/M) means a 90% discount on whatever you’d otherwise have to re-send.

But “preserves the prompt cache” comes with three asterisks. This guide covers the verified mechanics, the step-by-step, and the three edge cases that silently invalidate the cache anyway.

What You Can Do With /cd (And What You Can’t)

The 30-second mental model: /cd is “move the room you’re working in, keep everything you’ve already said.” /add-dir is “keep your current room, also let me peek into the room next door.” cd in Bash is neither — it changes one shell call and resets the next.

Decision Frame: When to Use /cd (and When NOT)

When to use /cd

1. You’re mid-plan on a complex refactor and realize the actual code lives in .worktrees/feature-x/ rather than the repo root.
2. You’re triaging across two sibling repos (backend/ and mobile/) and want to jump without losing your cache_read_input_tokens discount.
3. You opened the CLI from /Users/you/ by accident and the project is at /Users/you/projects/api/ — one command saves a restart.

When NOT to use /cd

1. You only need read/edit access to a second directory while keeping your working root — that’s /add-dir, which preserves more of the cache (it doesn’t touch the system block).
2. You’re scripting Claude Code non-interactively (claude -p "..."); pass the directory as the CWD when launching the process instead.
3. The new directory has a meaningfully different .mcp.json and you’re routing through a custom ANTHROPIC_BASE_URL or using a model where tool search isn’t available (Haiku, Vertex AI). In that combination the cache will rebuild anyway — restart for a cleaner state. A different CLAUDE.md alone is fine: /cd appends it as a message and keeps the cache.

Stop rule If your goal is just to read one file in another repo, stop at /add-dir plus Read /absolute/path/to/file. /cd is overkill and costs you a partial cache invalidation. If your goal is to write files there, /cd pays for itself.

System Requirements

If you’re below v2.1.169, upgrade: npm i -g @anthropic-ai/claude-code (the CLI auto-detects newer versions on launch).

Step-by-Step: Switch Directories Mid-Session

Step 1: Confirm your current root

Most sessions display the working root in the prompt prefix line. If yours doesn’t, just ask Claude which directory are you in? — it will print the absolute path from its tool context. Expected result: an absolute path to your current session root.

Step 2: Run /cd with an absolute path

> /cd /Users/you/projects/api/.worktrees/feature-payments

Claude Code prints a confirmation that the session has moved. Use absolute paths — relative paths like /cd ../mobile work but get resolved against the current root, which becomes confusing after two or three hops.

Step 3: Verify cache survival on the next message

Send any message and watch the cache_read_input_tokens and cache_creation_input_tokens values reported by the API on each turn. /cost (alias /usage) shows session-wide spend and plan usage, not per-turn cache counts — for live per-turn visibility the official docs recommend a statusline script that reads the current_usage object:

cache_read_input_tokens: 47,832    ← cache survived
cache_creation_input_tokens: 142   ← only the diff was written

A non-zero cache_read_input_tokens near your previous prefix size means /cd kept the cache hot. Zero reads plus a large cache_creation_input_tokens means something on the cache-key path changed — read the next section to find what.

Step 4: Continue working as if you’d opened the CLI in the new directory

Glob, Grep, and Bash now anchor on the new root. File writes land in the new tree. The plan-mode buffer, todo list, and conversation history all carry over. There’s no “session reset.”

Common Errors When Running /cd (and What They Mean)

The visible failure modes are easy to recognise. The silent ones — where /cd succeeds but the cache is dead — are covered in the next section.

3 Edge Cases That Silently Invalidate the Cache

These are the three failure modes most users hit. Each one is technically correct behavior (the cache is dirty), but the framing “preserves prompt cache” suggests universality, which is misleading.

Edge Case 1: New directory has a different CLAUDE.md (less severe than it looks)

This is the case most readers worry about, but /cd handles it cleverly. Per the official Claude Code /cd reference, the new directory’s CLAUDE.md is appended as a message rather than rebuilt into the system prompt:

/cd ~/projects/mobile     ← different CLAUDE.md
→ tools cache:    HIT
→ system cache:   HIT
→ messages cache: HIT (existing turns unchanged; new CLAUDE.md is appended)
+ small cache write for the appended CLAUDE.md content

The trade-off is that the new CLAUDE.md enters the conversation layer rather than the (cached) system layer, which costs a few hundred to a few thousand tokens of cache write depending on the file’s size, but leaves the cached prefix intact. The “tools cache lost” failure mode you might worry about doesn’t happen here.

Fix: There is no fix needed for cache behavior — the design already preserves it. The real concern with a different CLAUDE.md is semantic: rules written for project A may misguide the agent in project B. Keep one shared root-level ~/.claude/CLAUDE.md for cross-project rules and reserve project-local files for genuinely project-specific guidance.

Edge Case 2: Different MCP servers — only invalidates when tool search is off

This one is conditional. The official Claude Code prompt-caching docs note that deferred tools (the default on supported models) only append new content when an MCP server connects, disconnects, or changes its tool list — the cached prefix survives. Full cache rebuild on MCP changes only happens when tools load into the prefix, which is the case on Haiku models, on Vertex AI, or with a custom ANTHROPIC_BASE_URL gateway.

If you’re routing through a custom base URL (including ofox.ai), assume MCP changes invalidate:

/cd ~/projects/data-pipeline    ← adds a postgres MCP server, gateway routing
→ tools cache: MISS  (new tool definitions, not deferred)
→ system cache: MISS (cascades)
→ messages cache: MISS (cascades)

On a 100K-token prefix that’s roughly $0.625 in cache writes vs $0.05 in cache reads — about 12× more expensive than a clean /cd. On direct Anthropic with deferred tools, the same /cd is effectively free.

Fix: If you’re on direct Anthropic and supported models, you’re already covered. If you’re on a custom gateway, align MCP servers across the projects you bounce between, or hoist shared servers into user-level ~/.claude/settings.json so they don’t change with the working root. The Claude Code hooks, subagents, and skills guide walks through a clean user-level layout.

Edge Case 3: You already used /add-dir, then /cd to that added directory

This one’s subtle. If you ran /add-dir ~/projects/mobile earlier and then /cd ~/projects/mobile, the additional-directory grant is still active and the working root has moved into it. Tools that resolved paths via the additional-directory lookup table now also match the new working root, which causes some Bash invocations to receive different CWDs depending on whether the path was supplied as absolute or relative.

You won’t see a cache miss directly, but you’ll see Bash commands behave inconsistently — sometimes resolving against the original root, sometimes the new one — which costs you tool-call rounds (each of which is a cache write, not a read).

Fix: After /cd, re-check your /add-dir grants and remove any that overlap with the new working root — either through the slash command’s interactive prompt or by restarting from a clean state. Alternatively, prefer absolute paths in every Bash and file-write request after /cd, which sidesteps the resolution ambiguity entirely.

Cache Invalidation Matrix: What Survives /cd

The cache hierarchy comes from the Anthropic prompt caching documentation, which describes invalidation cascading down from tools through system into messages.

Team / Multi-Developer Configuration

For teams that share /cd patterns across many repos (the common case: a monorepo with multiple worktrees, or a polyrepo backend), three conventions keep the cache hot for everyone:

For organizations standardising Claude Code across the team, also consider a dotfiles-style shared ~/.claude/ layout in Chezmoi or Ansible. The first time you run /cd between two correctly-aligned worktrees, the next message’s cache_read_input_tokens will be identical to the prior turn — that’s how you verify the team config is right.

If you’ve hit the per-account rate limit on Anthropic’s direct API mid-session (where /cd’s cache savings matter most), an Anthropic-compatible gateway sidesteps the limit while preserving cache_control semantics. The integration takes one environment variable: see the Claude Code + ofox.ai configuration guide for the exact ANTHROPIC_BASE_URL setup. ofox routes the same model IDs (anthropic/claude-opus-4.8, anthropic/claude-sonnet-4.6) and passes cache headers through unchanged, so the math above doesn’t change.

Advanced: /cd in Multi-Provider Workflows

/cd is model-agnostic — it doesn’t care whether you’re hitting Anthropic directly, routing through ofox, or running a local fallback. But the cache savings only materialize on providers that honor cache_control. Three concrete tips:

1. Mixed providers per turn: If your session sometimes routes to Claude Opus 4.8 (cache-aware) and sometimes to a local model (no cache), /cd only helps the Claude-routed turns. Plan your /cd calls before high-cost prefix turns, not after.
2. Worktree-per-feature with shared base: Keep your base prompt and tool list identical across worktrees. The cache prefix hashes survive /cd only when the bytes are byte-identical, not “semantically equivalent.”
3. Long-running plans: If you’ve been in plan mode for 30+ minutes, the 5-minute TTL has expired and the cache is cold regardless of /cd. Use ENABLE_PROMPT_CACHING_1H=1 for a 1-hour TTL (2× cache write cost, but worth it for long planning sessions).

For deeper cache-hit math and a quantitative cost model for long sessions, see the Claude Code token optimization guide — the same cache_read_input_tokens / cache_creation_input_tokens metrics are the diagnostic surface for both. If you’re picking which Claude model to anchor your session on before /cd matters, the Claude Opus 4.8 release review covers the cache-pricing differences across the 4.6 / 4.7 / 4.8 line.

The mental model worth keeping: /cd is designed to preserve the prompt cache, and it largely does — CLAUDE.md changes are handled by appending the new file as a message, not by rebuilding the system prompt. The real failure mode is PreToolUse hook differences, or MCP server changes when you’re routing through a gateway that disables tool search. Hoist those into user-level config and /cd is effectively free.

Sources Checked for This Refresh

• Claude Code CHANGELOG (verified 2026-06-11): github.com/anthropics/claude-code/blob/main/CHANGELOG.md — confirmed /cd entry at v2.1.169
• Claude Code /cd command reference (verified 2026-06-11): code.claude.com/docs/en/commands — confirms CLAUDE.md is appended as a message, not rebuilt into the system prompt
• Claude Code prompt caching guide (verified 2026-06-11): code.claude.com/docs/en/prompt-caching — deferred tools behavior, ENABLE_PROMPT_CACHING_1H and FORCE_PROMPT_CACHING_5M env vars, statusline-based cache visibility
• Anthropic Prompt Caching docs (verified 2026-06-11): platform.claude.com/docs/en/build-with-claude/prompt-caching — cache hierarchy tools → system → messages and pricing multipliers (0.1× read, 1.25× 5-min write, 2.0× 1-hour write)
• GitHub issue #25322 “Allow switching working directory mid-session”: github.com/anthropics/claude-code/issues/25322 — original feature request and worktree pain points (closed as duplicate after /cd shipped)
• ofox model gallery snapshot (verified 2026-06-11): ofox.ai/en/models — Claude Opus 4.8 / 4.7 / 4.6 and Sonnet 4.6 pricing