anthropics / anthropics/claude-code

[QUESTION] Does stats-cache.json rebuild lose history for transcripts already cleaned up by cleanupPeriodDays or `project purge`?

Open
#94,479 0 comments 0 reactions 0 assignees View on GitHub
area:cli platform:macos question
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.