Claude Code Cache TTL Regression: 1h→5m Causes 20-32% Quota Inflation (v2.1.90/v2.1.108 Fix)

While waiting for or after applying fixes, reduce the impact of 5-minute TTL by keeping sessions shorter (one task per session), front-loading CLAUDE.md with critical context, and using the /compact command before pausing. This is a mitigation, not a fix — upgrade remains the primary solution.

1. Structure work into single-task sessions rather than marathon coding sessions spanning multiple hours
2. Move the most frequently needed context to the top of CLAUDE.md for better cache hit probability (cache reads from the prefix)
3. Use `/compact` proactively before pausing for > 5 minutes to reduce the context that will need to be re-cached on return
4. Avoid using cache-keepalive ping tools — they consume real tokens for cache reads that may never be used, and often cost more than they save

# Run inside Claude Code session before pausing:
/compact

# CLAUDE.md structure for cache efficiency (cache reads from start of message):
# TOP (~500 words): Project architecture overview, key file paths and their purposes, current task context, active constraints
# BOTTOM: Detailed coding conventions, long-form documentation references, historical notes

Use jq queries against Claude Code's JSONL session logs (~/.claude/projects/) to determine whether your sessions are using 1-hour or 5-minute TTL caching, identify which sessions and versions are affected, and verify the fix is working after upgrade.

1. Pre-check: verify JSONL files exist in ~/.claude/projects/ with `ls ~/.claude/projects/*.jsonl 2>/dev/null | head -5`
2. Run the TTL distribution query to see which dates/versions are affected
3. Run the 1h vs 5m summary query to get total token counts per TTL tier
4. Compare results before and after upgrade: 1h tokens should be non-zero post-upgrade

# Pre-check: verify JSONL files exist
ls ~/.claude/projects/*.jsonl 2>/dev/null | head -5 || echo 'NO_JSONL_FILES_FOUND'

# TTL distribution by date and version (filters non-haiku, non-sidechain):
grep -h -r -E 'ephemeral_.*_input_tokens' ~/.claude/projects/ 2>/dev/null | jq -r 'select((.isSidechain // true) == false and ((.message.model // "") | startswith("claude-haiku") | not) and (.message.usage.cache_creation.ephemeral_5m_input_tokens // 0) > 0) | (.timestamp // "unknown") + "," + (.version // "unknown")' 2>/dev/null | sed 's/T.*,/,/' | sort | uniq -c

# 1h vs 5m token summary:
find ~/.claude/projects/ -name '*.jsonl' -exec cat {} + 2>/dev/null | jq -s 'map(select(.message.usage.cache_creation)) | {total_1h_tokens: (map(.message.usage.cache_creation.ephemeral_1h_input_tokens // 0) | add), total_5m_tokens: (map(.message.usage.cache_creation.ephemeral_5m_input_tokens // 0) | add), api_call_count: length}' 2>/dev/null

Users who have disabled telemetry in Claude Code may be incorrectly classified as non-subscription users and given 5-minute TTL. Enabling telemetry ensures the server correctly identifies subscription status and applies 1-hour TTL where appropriate. This is necessary even after upgrading if you previously disabled telemetry.

1. Check if telemetry is disabled: look for CLAUDE_CODE_DISABLE_TELEMETRY or CLAUDE_CODE_TELEMETRY env vars
2. Remove or comment out any telemetry-disabling environment variables from shell profiles (~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish)
3. Remove telemetry-disable flags from any Claude Code configuration files in ~/.claude/
4. Restart Claude Code and verify telemetry status is no longer suppressed

env | grep -iE 'telemetry|CLAUDE_CODE_DISABLE' 2>/dev/null || echo 'NO_TELEMETRY_VARS_FOUND'

grep -r 'telemetry' ~/.claude/ 2>/dev/null | head -10 || echo 'NO_TELEMETRY_CONFIG_FOUND'

# BEFORE (remove these lines from ~/.bashrc or ~/.zshrc):
# export CLAUDE_CODE_DISABLE_TELEMETRY=1  ← DELETE
# export CLAUDE_CODE_TELEMETRY=false      ← DELETE

# AFTER (no telemetry-disabling vars should remain):
# (these lines should be absent from your shell profile)

Upgrade to v2.1.108 or later, which includes both the overage-latch bug fix (v2.1.90) and the telemetry-disabled fallback fix (v2.1.108). Version 2.1.108 and above contain both fixes and additional cache optimizations from Anthropic.

1. Check current Claude Code version: `claude --version` or `npm list -g @anthropic-ai/claude-code`
2. Upgrade to latest: `npm install -g @anthropic-ai/claude-code@latest`
3. Verify upgrade: `claude --version` should report >= 2.1.108
4. Restart all running Claude Code sessions after upgrade
5. Run a test session and check /cost to verify cache_read tokens are non-trivial

npm list -g @anthropic-ai/claude-code 2>/dev/null | grep claude-code

npm install -g @anthropic-ai/claude-code@latest

claude --version

# package.json (project-local install)
{
  "devDependencies": {
    "@anthropic-ai/claude-code": "^2.1.108"
  }
}