Prompt caching

Claude Code automatically uses prompt caching. You normally do not need to write cache_control yourself, but should understand which actions make the next turn slower or more expensive and how TTL choices differ.

See Commands and cache effects for command-by-command details. This page covers mechanics and diagnosis.

#Core concept

Every request resends system instructions, project context, history, tool results, and the new message. A cache hit lets the upstream reuse the identical prefix and process the appended content.

#Context layers

Earlier changes affect more of the prefix. Appending conversation content is generally easier to reuse than rebuilding the system prompt.

Cache identity also involves:

• Model: switching models does not reuse the old model's cache.
• Effort: changing effort can invalidate reuse.
• Fast-mode headers: initial activation can require a new cache.

Advisor is a special case: its tool definition is placed after the cache breakpoint, so toggling it generally preserves the existing prefix.

#Five minutes versus one hour

A hit refreshes TTL; five minutes is an inactivity interval, not the total lifetime. Official pricing is not a promise of Passion8 billing.

#Actions that invalidate reuse

MCP effects depend on whether definitions are deferred. Supported tool search improves prefix stability. Custom gateways or unsupported provider/model combinations can load tools upfront, making connection changes more disruptive.

#Changes that do not immediately replace the prefix

New root instructions and output styles apply when context is reloaded through the relevant new-session/compaction flow.

#Compaction cost

Compaction makes a summarization request, which can often read the existing prefix because the summary instruction is appended to the history.

Afterward, short summary content replaces the old conversation, and the next turn creates a cache for that shorter history.

• Compact at a natural task boundary.
• Avoid waiting for automatic compaction in a critical step.
• Use rewind, not compact, to abandon an incorrect direction.

#Subagents and forks

Subagents have separate conversations and caches. Their first call is usually cold; subsequent turns warm their own prefix. Their documented default TTL can differ from the subscription main conversation.

The invocation and final result append to the main conversation rather than replacing its prefix.

Fork/branch copies the conversation more directly, including instructions, tools, and history. Within TTL, the first fork turn may reuse the parent's prefix. Worktrees primarily isolate files and Git branches; see Worktrees.

#Usage fields

A higher read-to-write ratio suggests better reuse. Repeated creation means prefixes may be changing: check model, effort, style, MCP, tool denials, compaction, and CLI upgrades.

On Passion8 or another gateway, verify forwarding of anthropic-beta, tool schemas, output_config, context_management, cache fields, and usage. See Gateway and protocol.

#Disable or force TTL

# Disable all prompt caching
export DISABLE_PROMPT_CACHING=1

# Disable a model family
export DISABLE_PROMPT_CACHING_SONNET=1
export DISABLE_PROMPT_CACHING_OPUS=1
export DISABLE_PROMPT_CACHING_HAIKU=1
export DISABLE_PROMPT_CACHING_FABLE=1

# Optional one-hour TTL for API/provider requests
export ENABLE_PROMPT_CACHING_1H=1

# Force five minutes over one-hour settings
export FORCE_PROMPT_CACHING_5M=1

Disable caching only for diagnosis, not ordinary use.

#Cache-friendly workflow

Choose /model and /effort before starting the task.
Avoid repeatedly switching during the work.

#Official references

• How Claude Code uses prompt caching
• Commands
• Model configuration
• Gateway protocol reference
• Claude API prompt caching
• Output styles
• Status line
• Manage costs effectively