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

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:

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.

• Aider File Limits: Repo Map Scaling, File Addition Caps, and Context ManagementThe Aider file limit is not a rigid file count cap, but a boundary set by context windows and repository map budgets....
• How to Work Around Claude's File Upload LimitsClaude takes files of up to 500MB each and 20 per chat, but Project files cap at 30MB. Here are the exact limits by...
• Claude Artifact Size Limits: Token Ceilings, Rendering Caps, and WorkaroundsClaude artifact size limits are bounded by the model's maximum output token generation cap (typically 4,096 to 8,192...
• Claude Code Rate Limits: 5-Hour Usage Caps, 429 Errors, and WorkaroundsClaude Code rate limits enforce execution thresholds across terminal requests, tokens per minute, and five-hour rolling...
• Claude Code Cache TTL: Managing Prompt Cache Lifespans, Costs, and Context DriftClaude Code cache TTL determines how long system instructions, MCP tools, and conversation history remain in...
• Claude Code Message Limit: Quotas, Compaction, and Large-Context WorkaroundsClaude Code message limits define the maximum prompt token size and message frequency allowed in a CLI session before...

More on this subject: Claude and Claude Code (325 guides)

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.

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.

Keep Large Codebases Searchable Beyond Cache Limits

Connect Claude Code to a persistent Fast.io workspace using our streamable MCP server. Keep your repositories, specs, and architectural documentation indexed for fast semantic retrieval across coding sessions. Monthly plans include a 14-day free trial (credit card required).

Start 14-Day Trial

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.

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 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:

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 and storage for agents to see how teams organize agent context. For full setup instructions and client guides, consult the Fast.io MCP documentation.

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

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