Skip to main content

​
Overview

The stats-cache.json file contains pre-computed analytics about your Claude Code usage. This cache file aggregates data from all sessions to provide quick access to statistics, daily activity patterns, model-specific token usage, and cost estimates.

​
File Location

~/.claude/stats-cache.json

​
File Format

JSON format containing aggregated statistics across all sessions.

​
Data Structure

​
StatsCache Interface

export interface StatsCache {
  totalSessions: number;
  totalMessages: number;
  firstSessionDate: string;
  dailyActivity: DailyActivity[];
  dailyModelTokens: DailyModelTokens[];
  modelUsage: Record<string, ModelUsage>;
  hourCounts: Record<string, number>;
  longestSession: {
    sessionId: string;
    duration: number;
    messageCount: number;
    timestamp: string;
  };
  version?: string;
  lastComputedDate?: string;
}
​
totalSessions
number
required
Total number of coding sessions across all time
​
totalMessages
number
required
Total number of messages (user + assistant) sent
​
firstSessionDate
string
required
ISO timestamp of the first recorded session
​
dailyActivity
DailyActivity[]
required
Array of daily activity metrics. See DailyActivity structure below.
​
dailyModelTokens
DailyModelTokens[]
required
Daily token usage broken down by model. See DailyModelTokens structure below.
​
modelUsage
Record<string, ModelUsage>
required
Aggregate token usage and costs per model. Keys are model names. See ModelUsage structure below.
​
hourCounts
Record<string, number>
required
Message count by hour of day (0-23). Keys are hour strings.
​
longestSession
object
required
Metadata about your longest coding session
​
version
string
Version of the stats cache schema
​
lastComputedDate
string
ISO timestamp of when the cache was last computed

​
DailyActivity Structure

export interface DailyActivity {
  date: string;
  messageCount: number;
  sessionCount: number;
  toolCallCount: number;
}
​
date
string
required
Date in YYYY-MM-DD format
​
messageCount
number
required
Total messages sent on this day
​
sessionCount
number
required
Number of sessions started on this day
​
toolCallCount
number
required
Total tool invocations on this day

​
DailyModelTokens Structure

export interface DailyModelTokens {
  date: string;
  tokensByModel: Record<string, number>;
}
​
date
string
required
Date in YYYY-MM-DD format
​
tokensByModel
Record<string, number>
required
Token counts keyed by model name (e.g., "claude-4.5-sonnet": 125000)

​
ModelUsage Structure

export interface ModelUsage {
  inputTokens: number;
  outputTokens: number;
  cacheReadInputTokens: number;
  cacheCreationInputTokens: number;
  webSearchRequests: number;
  costUSD?: number;
  contextWindow?: number;
  maxOutputTokens?: number;
}
​
inputTokens
number
required
Total input tokens consumed by this model
​
outputTokens
number
required
Total output tokens generated by this model
​
cacheReadInputTokens
number
required
Tokens read from prompt cache (cheaper than regular input)
​
cacheCreationInputTokens
number
required
Tokens used to create prompt cache entries
​
webSearchRequests
number
required
Number of web search tool invocations
​
costUSD
number
Estimated cost in USD for this model’s usage
​
contextWindow
number
Maximum context window size for this model
​
maxOutputTokens
number
Maximum output token limit for this model

​
Loading Function

From src/lib/load-data.ts: 
const CLAUDE_DIR = path.join(process.env.HOME || "~", ".claude");

export function loadStatsCache(): StatsCache | null {
  try {
    const raw = fs.readFileSync(path.join(CLAUDE_DIR, "stats-cache.json"), "utf-8");
    return JSON.parse(raw);
  } catch {
    return null;
  }
}
Returns null if the file doesn’t exist or can’t be parsed. This is normal for new installations.

​
Usage in Export Script

From scripts/export.mjs: 
// 1. Stats cache
let stats = null;
try {
  stats = JSON.parse(fs.readFileSync(path.join(CLAUDE_DIR, "stats-cache.json"), "utf-8"));
  console.log("  stats-cache.json ✓");
} catch {
  console.log("  stats-cache.json ✗ (not found)");
}

// Include in export
const data = {
  stats,
  sessions,
  history,
  memories,
  account: Object.keys(account).length > 0 ? account : undefined,
  exportedAt: new Date().toISOString(),
};
fs.writeFileSync(OUTPUT, JSON.stringify(data));
The export script:
  1. Attempts to read stats-cache.json
  2. Logs success or failure
  3. Includes the parsed stats (or null) in the export bundle

​
Use Cases

  • Activity Heatmap: dailyActivity powers the GitHub-style contribution grid
  • Model Breakdown: modelUsage displays pie charts and cost tables
  • Daily Token Chart: dailyModelTokens shows stacked area charts of token consumption
  • Hour Distribution: hourCounts reveals when you code most
  • Summary Stats: totalSessions, totalMessages, and longestSession appear in stat cards

Build docs developers (and LLMs) love

Get started for freeTalk to us