[DOCS] `/stats` docs omit date ranges, retention semantics, and usage aggregation details

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/commands

Section/Topic

/stats command behavior, especially date ranges, retention semantics, and what usage is counted

Current Documentation

The command reference currently describes /stats in one line:

| /stats | Visualize daily usage, session history, streaks, and model preferences |

The costs page adds only this note:

The /cost command shows API token usage and is intended for API users. Claude Max and Pro subscribers have usage included in their subscription, so /cost data isn't relevant for billing purposes. Subscribers can use /stats to view usage patterns.

The settings page separately says:

| cleanupPeriodDays | Sessions inactive for longer than this period are deleted at startup (default: 30 days). Setting to 0 deletes all existing transcripts at startup and disables session persistence entirely. No new .jsonl files are written, /resume shows no conversations, and hooks receive an empty transcript_path. |

Related docs explain some contributing concepts elsewhere, but not how /stats handles them:

If the parent uses auto mode, the subagent inherits auto mode and any permissionMode in its frontmatter is ignored: the classifier evaluates the subagent's tool calls with the same block and allow rules as the parent session.

Subagent transcripts persist independently of the main conversation: * Automatic cleanup: Transcripts are cleaned up based on the cleanupPeriodDays setting (default: 30 days).

What's Wrong or Missing?

Two v2.1.88 changelog entries expose behavior that the docs still do not explain:

Fixed /stats losing historical data beyond 30 days when the stats cache format changes

Fixed /stats undercounting tokens by excluding subagent/fork usage

The changelog for v2.1.6 also added /stats range filtering with "Last 7 days", "Last 30 days", and "All time", but the reference docs still leave /stats as a one-line summary.

That leaves several gaps:

A. Date ranges are undocumented

Users are not told that /stats supports multiple ranges such as "Last 7 days", "Last 30 days", and "All time", or how to switch between them.

B. Retention semantics are ambiguous

The only documented retention rule is cleanupPeriodDays, which deletes old transcripts after 30 days by default. The v2.1.88 changelog shows /stats is expected to preserve history older than that window, but the docs never explain how /stats history relates to transcript cleanup.

C. Usage-accounting scope is undocumented

The current docs do not explain whether /stats includes token-based usage data for subscribers, whether delegated work from subagents is rolled up into the same totals, or whether forked/branched session activity is included.

D. The v2.1.88 behavior change is only visible in the changelog

If /stats totals or history change after upgrading, there is no reference page explaining that earlier builds could undercount usage or lose older historical data during cache-format changes.

Suggested Improvement

Add a dedicated /stats subsection on the command docs, or a separate /stats page linked from commands and costs, that explains:

1. the available date ranges, including "Last 7 days", "Last 30 days", and "All time"
2. how to switch ranges in the UI
3. whether cleanupPeriodDays affects only stored session transcripts, or also the history shown in /stats
4. whether /stats includes token-based usage totals for subscribers
5. whether those totals aggregate delegated work from subagents and relevant forked session activity
6. how /stats differs from /cost, which is API-focused and session-scoped

Even a short note would help, for example: "/stats can show aggregated historical usage beyond the local transcript retention window. cleanupPeriodDays controls transcript cleanup on disk; document separately whether it changes the data shown in /stats. Subscriber usage totals also include delegated work such as subagents where applicable."

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/commands | Primary /stats command reference is currently a one-line summary |
| https://code.claude.com/docs/en/costs | Tells subscribers to use /stats, but not what data /stats includes |
| https://code.claude.com/docs/en/settings | cleanupPeriodDays documents transcript deletion, which makes /stats retention semantics ambiguous |
| https://code.claude.com/docs/en/sub-agents | Explains subagent transcripts and cleanup separately, but not whether /stats aggregates subagent usage |

Total scope: 4 pages affected

Source: Changelog v2.1.88

Changelog entries:

Fixed /stats losing historical data beyond 30 days when the stats cache format changes

Fixed /stats undercounting tokens by excluding subagent/fork usage

Related changelog context: v2.1.6 also added /stats range filtering with "Last 7 days", "Last 30 days", and "All time".