anthropics / anthropics/claude-code
[FEATURE] Expose a "why did this cache miss happen" diagnostic
- Lenguaje dominante
- Python
- Estrellas
- 145k
- Forks
- 23.1k
- Métricas de merge de PR
- Métricas de PR pendientes
Descripción
## Is your feature request related to a problem?
There are many open issues reporting the same underlying symptom from different triggers: a prompt-cache prefix that should have hit unexpectedly misses and gets fully rewritten (`cache_creation` instead of `cache_read`) — e.g. #82563, #83542, #85326, #63930, #87966, #78420, #78660, #78720, #86244, #90716, #90363, #87227. Each report figured out its trigger by manual trial and error, and each is filed as if it were an independent bug.
We hit the same wall from the outside, building a local profiler that measures Claude Code's cache behavior via proxy traces: a cache miss is just a number going up in `usage.cache_creation_input_tokens`, with no signal about *why* the prefix that matched last turn didn't match this turn.
## Describe the solution you'd like
A lightweight diagnostic (a flag, a `/context`-style command, or a verbose log line) that reports, per request, when the effective cached prefix diverges from the previous turn's:
- how much of the previous prefix was still stable (length of the matching prefix before the first difference),
- roughly where the first byte/segment diverged (e.g. "system prompt", "tool definitions", "message N"),
- and, if knowable, what changed it (a date/timestamp injection, a hook-added block, a tool-array mutation, TTL expiry, a compaction/rewrite of history, etc).
This wouldn't require fixing any individual trigger — it would let users, and issue reporters, self-diagnose instead of every trigger needing its own from-scratch investigation and its own GitHub issue. That's a meaningful part of why the list of "stable prefix unexpectedly rewritten" issues above is as long as it is for what looks like a handful of underlying causes reported many different ways.
## Additional context
We searched existing issues under several phrasings ("cache invalidation diagnostic", "why cache miss happened", "stable prefix length", "first diverging byte") and found requests for fixes to specific triggers, but nothing asking for a generic diagnostic surface.
Guía de contribución
No hay ninguna guía de contribución indexada para este repositorio
Línea de trabajo
No files, tests, or entry points are named in the issue. Start by locating the request and prompt-cache handling, then determine how a per-request diagnostic could expose stable-prefix length, divergence location, and known causes; done means users can identify why a cache miss occurred without reproducing it by trial and error.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Stack tecnológico
- python
- Área
- cli, performance
- Tipo de issue
- Nueva funcionalidad
- Dificultad
- 5/5
- Tiempo estimado
- Más de una semana
- Estado de actividad
- Activo
- Claridad
- Necesita aclaración
- Aptitud para principiantes
- 30/100