# Claude Code Cache Limits: Breakpoints, Thresholds, and Cost Management

Claude Code prompt caching relies on Anthropic's four-breakpoint ceiling, strict minimum token thresholds, and a five-minute inactivity window. Understanding how cache prefixes invalidate across multi-file codebases prevents unexpected cost spikes and keeps terminal sessions responsive.

Source: https://fast.io/resources/claude-code-cache-limit/
Author: [Derek Labian](https://fast.io/authors/derek-labian/)
Last reviewed: 2026-11-07

## What Are the Documented Cache Limits for Claude Code?

In Anthropic's platform guidelines documented in the Claude file upload documentation, chat uploads accept up to 20 files per chat session at up to 500MB each. Claude Projects accepts individual documents without a fixed file-count cap, provided the total content fits within Claude's context window. Claude Projects has no fixed file-count cap, so the operational ceiling for attached documentation is the model context window itself.

When developers move from static web chats to Claude Code in the terminal, context management shifts from file attachments to dynamic prompt caching over the Messages API. In this environment, prompt caching controls latency, context preservation, and API billing.

Claude Code cache limits represent the architectural constraints on Anthropic's prompt caching in Claude Code, including a 4-breakpoint ceiling and minimum token thresholds.

Because large language models are stateless, Claude Code must resend project instructions, system prompts, tool schemas, file contents, and accumulated conversation history with every prompt turn. Without prompt caching, token consumption expands rapidly with each interaction. Prompt caching stores the computational state of reusable prompt prefixes on Anthropic's servers, allowing subsequent requests that share an identical prefix to skip redundant prefill computation.

The table below outlines the core limits governing prompt caching in Claude Code:

| Cache Parameter | Documented Limit | Operating Scope | Behavior When Threshold Is Missed |
|---|---|---|---|
| Maximum Cache Breakpoints | 4 per request | Request-wide across tools, system, messages | Requests with more than 4 explicit breakpoints fail with HTTP 400 |
| Minimum Cacheable Prefix (Sonnet and Opus) | 1,024 tokens | Claude 3.5 Sonnet, Claude 3 Opus | Blocks under 1,024 tokens are billed as standard uncached input |
| Minimum Cacheable Prefix (Haiku) | 2,048 tokens | Claude 3 Haiku | Blocks under 2,048 tokens are billed as standard uncached input |
| Default Inactivity TTL | 5 minutes | Inactivity lifetime | Cache expires; next prompt is billed as a fresh cache write |
| Extended Cache TTL | 1 hour | Ephemeral header flag | Retains cache for longer batch workflows at adjusted write rates |
| Eviction Triggers | Exact prefix mismatch | Byte-level prompt comparison | Any edit to upstream tokens invalidates all downstream cached blocks |

Developers tracking their terminal sessions can inspect token usage reports directly in Claude Code to see how many tokens hit the cache versus fresh writes. Understanding these boundaries is critical before adding large documentation sets to local development repositories.

### How Anthropic Structures Request Hierarchy and Prefix Matching

Prompt caching in Claude Code does not store disconnected text snippets. It stores a deterministic cryptographic snapshot of the exact sequence of tokens processed up to a specified boundary. Anthropic processes requests in a strict structural order:

1. Tools: Definitions and schemas for terminal execution, file reading, and external MCP connectors.
2. System Prompts: Base instructions, project conventions defined in files like `CLAUDE.md`, and environment metadata.
3. Messages: The chronological history of user prompts, tool call executions, and assistant responses.

Cache evaluation proceeds strictly from left to right along this sequence. Anthropic compares incoming tokens against existing cached prefixes. The instant a token differs, cache matching stops, and all subsequent tokens must be computed afresh.

## Why the Four-Breakpoint Ceiling Fails on Small Codebases

Anthropic prompt caching allows defining up to 4 cache breakpoints per request using explicit `cache_control` parameters. While basic documentation explains prompt caching TTL, it rarely addresses how cache breakpoints fail when developers work in repositories containing hundreds of small source files.

In modern modular codebases, applications often consist of dozens or hundreds of small source files, each spanning between 50 and 400 tokens (utility modules, React components, configuration files, schema definitions). Developers working with Claude Code encounter three distinct architectural obstacles:

* **Breakpoint Exhaustion:** If you attempt to assign individual cache breakpoints to each source file so that edits to one file do not invalidate the others, the request immediately fails with an HTTP 400 error. Anthropic prompt caching rejects any request that attempts to define more than 4 cache breakpoints.
* **Minimum Threshold Rejection:** Even if Anthropic permitted unlimited breakpoints, individual small files fail the minimum token size threshold. Claude 3.5 Sonnet and Claude 3 Opus require at least 1,024 tokens to activate prompt caching, while Claude 3 Haiku requires 2,048 tokens. Blocks below these thresholds are processed as standard uncached input, providing zero caching benefit.
* **Monolithic Invalidation:** The common workaround is to concatenate all small files into a single large context block before the conversation turns. While this easily exceeds the 1,024-token minimum, it makes the cache brittle. Changing a single comment or adding one line of code to any file in that combined block alters the prefix hash. The entire block is evicted from the cache, triggering a complete cache write penalty on the next turn.

This architectural dilemma forces developers to choose between paying full price for uncached small files or suffering frequent cache invalidations when files are grouped into single blocks.

## How Cache Eviction and the Five-Minute Inactivity Window Impact Costs

Anthropic prompt caching entries have a default Time-To-Live of 5 minutes. Every cache read hit resets the 5-minute timer. When a developer sends prompts continuously, the warm cache remains active, and token costs stay predictable.

Real software engineering does not happen continuously. Developers run integration tests, inspect compiler warnings, review git diffs, consult documentation, or step away from their desk.

When inactivity exceeds 5 minutes, Anthropic purges the cached computational state from GPU memory. On the following prompt, Claude Code incurs a cache miss.

The economic penalty is twofold:

1. The prompt cannot benefit from discounted cache read pricing.
2. Anthropic bills the request at the cache write rate, which costs 25 percent more than baseline uncached input tokens, in order to write the prefix back into memory.

For a large codebase payload of 80,000 tokens, a warm cache read costs a fraction of the fresh input rate. But if a developer pauses for 6 minutes between questions, every prompt becomes a full cache write. Across an 8-hour workday with repeated pauses, token costs can double or triple compared to steady interactions.

Anthropic provides an extended 1-hour TTL option for batch workflows. However, this extended retention carries a higher initial cache write cost. For interactive local development where files change frequently, the 1-hour TTL often incurs higher upfront write costs without preventing invalidations caused by local edits.

## Best Practices to Optimize Claude Code Cache Utilization and Costs

Developers can adopt disciplined habits to maximize cache efficiency in Claude Code:

1. **Keep System Instructions Strictly Immutable:** Avoid placing dynamic variables (such as timestamps, fluctuating environment variables, or active git commit hashes) inside `CLAUDE.md` or system prompts. Keep static guidelines at the top so the system prompt prefix remains identical across every turn.
2. **Order Tools Stably:** Ensure tool definitions and MCP server configurations are registered in a fixed order. Swapping tool registrations invalidates the entire message prefix downstream.
3. **Prune Conversation History with Terminal Commands:** As conversation history lengthens, tool outputs and terminal logs accumulate. Use Claude Code's `/compact` command to summarize older turns before conversation size pushes latency and cost beyond practical boundaries.
4. **Query Targeted Files Rather Than Ingesting Whole Repositories:** Avoid commands that load the entire directory structure into memory. Inspect specific functions or modules on demand rather than asking Claude Code to ingest hundreds of uncached source files simultaneously.
5. **Distinguish Long-Term Reference from Ephemeral Working State:** Stable architectural guidelines, API contracts, and design documentation belong in static reference storage, while active code edits remain in the terminal.

## How Fast.io Indexes Large Repositories Beyond Context and Cache Limits

When codebases grow beyond tens of thousands of lines of code, or when teams need to query extensive architectural specs, API references, and product manuals, forcing the entire corpus into Claude Code's prompt cache becomes unsustainable. Trying to force hundreds of files into local prompt memory causes fragile invalidations, breakpoint exhaustion, and runaway token bills.

Rather than overloading the prompt cache with documentation files that frequently invalidate each other, teams use [Fast.io Workspaces](/product/workspaces/) as an external knowledge substrate.

The architecture separates active code editing from background knowledge retrieval:

* **Centralized Project Storage:** Repository documentation, API specs, database schemas, and shared assets are stored in an organization-owned Fast.io workspace. Files can be imported directly or synced from Google Drive, Dropbox, Box and OneDrive on a schedule or on demand.
* **Automated Semantic Indexing:** When Intelligence Mode is enabled on the workspace, Fast.io automatically indexes documents for full-text search and semantic search without external vector databases.
* **Streamable MCP Connection:** Claude Code connects directly to Fast.io using the remote MCP server at `https://mcp.fast.io/mcp/code`. Setup requires a single command in your project directory:

```bash
claude mcp add --transport http fast-io https://mcp.fast.io/mcp/code
```

Run `/mcp` inside Claude Code to complete authentication in your browser.

When Claude Code needs context about system architecture, internal APIs, or historical changes, it queries the workspace through Fast.io's consolidated MCP toolset. The MCP server performs semantic search and returns only the relevant excerpts (typically 200 to 500 tokens) directly to the model.

This architecture leaves Anthropic's prompt cache limits untouched. The prompt cache stays lightweight, containing only the current task and immediate file context, while the vast knowledge base remains accessible via search without triggering token bloat, breakpoint exhaustion, or 5-minute eviction penalties.

Explore [Fast.io AI storage](/product/ai/) and [storage for agents](/storage-for-agents/) to see how teams organize agent context. For full setup instructions and client guides, consult the [Fast.io MCP documentation](https://mcp.fast.io/docs).

Fast.io plans are structured for teams of all sizes:

| Plan | Monthly Pricing | Storage Allowance | Included Seats | Monthly AI Credits |
|---|---|---|---|---|
| Starter | $9.99/mo | 250 GB | 3 seats | 100,000 credits |
| Business | $49.99/mo | 5 TB | 10 seats | 600,000 credits |
| Enterprise | $199.99/mo | 25 TB | 30 seats | 3,000,000 credits |

Monthly plans start with a 14-day free trial that requires a credit card. Check the [pricing page](/pricing/) for full details on plan options and team collaboration features.

## Frequently asked questions

### What are the limits on Claude Code prompt caching?

Claude Code prompt caching operates under Anthropic's platform limits: a maximum of 4 cache breakpoints per request, minimum cacheable prefix sizes of 1,024 tokens for Claude 3.5 Sonnet and Claude 3 Opus (2,048 tokens for Claude 3 Haiku), and a default 5-minute inactivity expiration window. Exceeding 4 breakpoints causes an HTTP 400 error, while blocks below the minimum token threshold are processed as uncached input.

### How many cache breakpoints does Claude Code support?

Claude Code supports up to 4 cache breakpoints per request, enforced by Anthropic's Messages API. These breakpoints mark specific locations in the prompt hierarchy (such as tool definitions, system prompts, or specific message turns) to preserve cached token prefixes across turns.

### Why is Claude Code cache not working on small files?

Small files fail to activate prompt caching individually because Anthropic enforces a minimum prefix threshold of 1,024 tokens for Sonnet and Opus models, and 2,048 tokens for Haiku. Files smaller than this threshold cannot form an independent cache breakpoint. When multiple small files are concatenated into one cached block, editing any single file invalidates the entire block.

### How does cache eviction work during long coding sessions?

Cache entries automatically expire after 5 minutes of inactivity. When a developer pauses to test code or read documentation for more than 5 minutes, the next prompt results in a cache miss. Claude Code must then perform a fresh cache write, which is billed at a higher rate than standard input tokens to store the prompt prefix back into GPU memory.

### How can teams provide large documentation to Claude Code without blowing context limits?

Instead of attaching large file sets directly to prompts, teams store reference documentation in a Fast.io workspace with Intelligence Mode enabled. Claude Code connects via the remote MCP server at `https://mcp.fast.io/mcp/code` and retrieves relevant snippets through semantic search on demand, keeping local prompt caches small and stable.

## Sources

- [Anthropic Claude Documentation](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching): Anthropic prompt caching allows defining up to 4 cache breakpoints per request.
- [Anthropic Support: Upload files to Claude](https://support.claude.com/en/articles/8241126-upload-files-to-claude): Anthropic Claude chat uploads permit up to 20 files per chat session.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli. MCP setup is at https://mcp.fast.io/docs: Claude and most MCP clients connect to https://mcp.fast.io/mcp/tools, ChatGPT to https://mcp.fast.io/mcp/operations, and coding agents to https://mcp.fast.io/mcp/code.