anthropics / anthropics/claude-code
[QUESTION] Does stats-cache.json rebuild lose history for transcripts already cleaned up by cleanupPeriodDays or `project purge`?
- Dominant language
- Python
- Stars
- 145k
- Forks
- 23.1k
- PR merge metrics
- PR metrics pending
Description
Related to #59248.
### Context
The docs ([claude-directory#application-data](https://code.claude.com/docs/en/claude-directory)) list `~/.claude/stats-cache.json` (aggregated totals shown by `/usage`) under "Kept until you delete them" — explicitly exempt from both the `cleanupPeriodDays` retention sweep and `claude project purge`. This is good: it means the historical `/usage` totals are already decoupled from the raw session transcripts they were presumably built from.
### What I found reading the client
Reading the strings in the installed `claude` CLI binary (v2.1.272), the stats aggregation code (functions building an object shaped like `{lastComputedDate, dailyActivity, dailyModelTokens, totalSessions, totalMessages, ...}`) has a fallback path: when the cache's `version` doesn't match, or `lastComputedDate` looks invalid, it logs `"resetting aggregates for a full rescan"` and appears to rebuild the aggregate by scanning `~/.claude/projects/**/*.jsonl` from scratch.
### The question
If that full-rescan path is ever triggered (cache corruption, a stats-cache schema version bump on upgrade, etc.), and the user has since had some transcripts removed — either by the default 30-day `cleanupPeriodDays` sweep, or by `claude project purge` — does the rebuilt cache still contain the historical totals for that now-gone period, or does that period silently disappear from `/usage`'s lifetime totals?
The docs don't say either way, and neither `project purge`'s dry-run/plan output nor `/usage` itself warns about this possibility.
If the answer is "it's lost," that's the same class of problem as #59248 (silent, unrecoverable, no warning) but specific to the aggregated stats rather than the transcripts themselves.
### Ask
1. Clarify whether the full-rescan path can actually drop already-known historical periods when their source transcripts no longer exist.
2. If so, consider having the rescan preserve previously-cached daily/period entries instead of discarding them when the source transcript is gone — i.e. treat `stats-cache.json` as the source of truth for periods it already covers, and only use transcripts to fill gaps it doesn't have yet.
3. Either way, documenting this explicitly in the "Kept until you delete them" section would help, since a user reading that section today would reasonably assume `/usage` totals are permanent regardless of `cleanupPeriodDays` or `project purge`.
### Environment
- Claude Code CLI 2.1.272 (also bundled in Claude Desktop)
- macOS
Contributor guide
No contributing guide indexed for this repository
Research direction
Review the stats-cache.json handling and the /usage full-rescan path, then compare results after transcripts are removed by cleanupPeriodDays or project purge. Check the application-data documentation and project purge dry-run output for existing guidance. Done means confirming whether historical totals survive a rebuild and documenting or addressing the observed behavior.
Written by the indexing model from the issue text.
Assessment
- Domain
- cli, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100