Data Model

Overview

All TypeScript interfaces are defined in src/lib/types.ts. The data model represents Claude Code usage analytics, parsed from various JSON and JSONL files in the ~/.claude/ directory.

Core Types

DashboardData

Root data structure passed from server/upload to the dashboard.

src/lib/types.ts

export interface DashboardData {
  stats: StatsCache | null;
  sessions: SessionMeta[];
  history: HistoryEntry[];
  memories: ProjectMemory[];
  account?: AccountInfo;
  exportedAt?: string;
}

stats

StatsCache | null

Pre-aggregated statistics from stats-cache.json. May be null if cache doesn’t exist.

sessions

SessionMeta[]

Array of per-session metadata objects, sorted by start_time descending

history

HistoryEntry[]

Prompt history from history.jsonl

memories

ProjectMemory[]

Project memory files with content (up to 5000 chars per file)

account

AccountInfo

Account identifiers extracted during export. Only present in uploaded files.

exportedAt

string

ISO timestamp when export was created. Only present in uploaded files.

StatsCache

Pre-aggregated statistics computed by Claude Code itself. This data cannot be derived from session metadata alone.

src/lib/types.ts

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

Total number of sessions recorded

totalMessages

number

Total messages across all sessions (user + assistant)

firstSessionDate

string

ISO date string of the first recorded session (e.g., "2025-01-15")

dailyActivity

DailyActivity[]

Daily breakdown of activity metrics

dailyModelTokens

DailyModelTokens[]

Daily token usage by model

modelUsage

Record<string, ModelUsage>

Per-model token breakdown and costs. Keys are model names like "claude-3-7-sonnet-20250219"

hourCounts

Record<string, number>

Sessions per hour of day. Keys are “0” through “23”

longestSession

object

Metadata about the longest session by duration

Show properties

sessionId

string

Unique session identifier

duration

number

Duration in milliseconds

messageCount

number

Total messages in the session

timestamp

string

ISO timestamp when session started

version

string

Cache format version

lastComputedDate

string

When stats cache was last computed

SessionMeta

Per-session metadata from ~/.claude/usage-data/session-meta/*.json.

src/lib/types.ts

export interface SessionMeta {
  session_id: string;
  project_path: string;
  start_time: string;
  duration_minutes: number;
  user_message_count: number;
  assistant_message_count: number;
  tool_counts: Record<string, number>;
  languages: Record<string, number>;
  git_commits: number;
  git_pushes: number;
  input_tokens: number;
  output_tokens: number;
  first_prompt: string;
  user_interruptions: number;
  tool_errors: number;
  tool_error_categories: Record<string, number>;
  uses_task_agent: boolean;
  uses_mcp: boolean;
  uses_web_search: boolean;
  uses_web_fetch: boolean;
  lines_added: number;
  lines_removed: number;
  files_modified: number;
  message_hours: number[];
  user_message_timestamps: number[];
}

session_id

string

Unique identifier for the session

project_path

string

Absolute path to the project directory (e.g., /Users/john/projects/my-app)

start_time

string

ISO timestamp when session started

duration_minutes

number

Session duration in minutes

user_message_count

number

Number of messages sent by the user

assistant_message_count

number

Number of messages sent by Claude

tool_counts

Record<string, number>

Tool usage counts by tool name (e.g., {"Read": 42, "Edit": 15})

languages

Record<string, number>

Language usage by line count (e.g., {"TypeScript": 200, "CSS": 50})

git_commits

number

Number of git commits made during session

git_pushes

number

Number of git pushes during session

input_tokens

number

Total input tokens consumed

output_tokens

number

Total output tokens generated

first_prompt

string

The first prompt text from the session

user_interruptions

number

Times user interrupted Claude’s response

tool_errors

number

Number of tool execution errors

tool_error_categories

Record<string, number>

Error counts by category

uses_task_agent

boolean

Whether session used task agents

uses_mcp

boolean

Whether session used MCP (Model Context Protocol)

uses_web_search

boolean

Whether session used web search

uses_web_fetch

boolean

Whether session used web fetch

lines_added

number

Total lines of code added

lines_removed

number

Total lines of code removed

files_modified

number

Number of files modified

message_hours

number[]

Array of hours (0-23) when messages were sent

user_message_timestamps

number[]

Unix timestamps (milliseconds) of user messages

DailyActivity

Daily activity metrics for the heatmap visualization.

export interface DailyActivity {
  date: string;           // ISO date "YYYY-MM-DD"
  messageCount: number;
  sessionCount: number;
  toolCallCount: number;
}

DailyModelTokens

Daily token consumption by model.

export interface DailyModelTokens {
  date: string;                          // ISO date "YYYY-MM-DD"
  tokensByModel: Record<string, number>; // Model name → total tokens
}

ModelUsage

Token and cost breakdown for a single model.

export interface ModelUsage {
  inputTokens: number;
  outputTokens: number;
  cacheReadInputTokens: number;
  cacheCreationInputTokens: number;
  webSearchRequests: number;
  costUSD?: number;
  contextWindow?: number;
  maxOutputTokens?: number;
}

inputTokens

number

Total input tokens consumed

outputTokens

number

Total output tokens generated

cacheReadInputTokens

number

Tokens read from cache (reduced cost)

cacheCreationInputTokens

number

Tokens used to create cache entries

webSearchRequests

number

Number of web search requests made

costUSD

number

Total cost in USD for this model

contextWindow

number

Model’s context window size

maxOutputTokens

number

Model’s maximum output token limit

HistoryEntry

Single prompt from ~/.claude/history.jsonl.

export interface HistoryEntry {
  display: string;
  pastedContents: Record<string, unknown>;
  timestamp: number;
  project: string;
}

display

string

The prompt text as displayed in the UI

pastedContents

Record<string, unknown>

Any content pasted along with the prompt

timestamp

number

Unix timestamp in milliseconds

project

string

Project path where prompt was used

ProjectMemory

Memory files from ~/.claude/projects/<id>/memory/.

export interface ProjectMemory {
  project: string;
  files: { name: string; content: string }[];
}

project

string

Encoded project directory name (slashes replaced with dashes)

files

array

Array of memory files

Show File object

name

string

Filename (e.g., "MEMORY.md")

content

string

File content, truncated to 5000 characters

AccountInfo

Account identifiers extracted from Statsig cache during export.

export interface AccountInfo {
  accountUUID?: string;
  organizationUUID?: string;
  appVersion?: string;
}

accountUUID

string

Unique account identifier

organizationUUID

string

Organization identifier (for team accounts)

appVersion

string

Claude Code application version

SessionMessage

Individual message from a session transcript, loaded via API route.

export interface SessionMessage {
  role: "user" | "assistant";
  text: string;
  timestamp: string;
  toolUse?: { name: string; id: string }[];
}

role

'user' | 'assistant'

Message sender

text

string

Message content, truncated to 5000 characters

timestamp

string

ISO timestamp when message was sent

toolUse

array

Tools used in this message (assistant messages only)

Show Tool object

name

string

Tool name (e.g., "Read", "Edit")

string

Unique tool use ID

Data Relationships

Aggregation Flow: Raw session data (SessionMeta[]) is aggregated into StatsCache by Claude Code. The analytics app consumes both to provide comprehensive insights.

Export JSON Format

The scripts/export.mjs script produces a single JSON file:

{
  "stats": {
    "totalSessions": 342,
    "totalMessages": 8451,
    "firstSessionDate": "2025-01-15",
    "dailyActivity": [...],
    "dailyModelTokens": [...],
    "modelUsage": {...},
    "hourCounts": {...},
    "longestSession": {...}
  },
  "sessions": [
    {
      "session_id": "abc123",
      "project_path": "/Users/john/project",
      "start_time": "2026-03-04T10:00:00Z",
      "duration_minutes": 45,
      ...
    }
  ],
  "history": [...],
  "memories": [
    {
      "project": "-Users-john-project",
      "files": [
        {
          "name": "MEMORY.md",
          "content": "# Project Context\n..."
        }
      ]
    }
  ],
  "account": {
    "accountUUID": "550e8400-e29b-41d4-a716-446655440000",
    "organizationUUID": "...",
    "appVersion": "1.2.3"
  },
  "exportedAt": "2026-03-04T12:00:00.000Z"
}

Source Files on Disk

stats-cache.json

Pre-aggregated statisticsLocation: ~/.claude/stats-cache.jsonFormat: JSON

session-meta/*.json

Per-session metadata filesLocation: ~/.claude/usage-data/session-meta/Format: One JSON file per session

history.jsonl

Prompt historyLocation: ~/.claude/history.jsonlFormat: Newline-delimited JSON

memory/*.md

Project memory filesLocation: ~/.claude/projects/<id>/memory/Format: Markdown

<session>.jsonl

Full session transcriptsLocation: ~/.claude/projects/<id>/Format: Newline-delimited JSON

statsig cache

Account informationLocation: ~/.claude/statsig/Format: JSON (read during export only)

Backward Compatibility

The upload zone (upload-zone.tsx) handles old export formats:

Auto-normalizes old memory format where files contained plain strings instead of {name, content} objects

Gracefully handles missing account and exportedAt fields

Validates JSON structure before processing

Memory Format Normalization

// Normalize old memory format (string[] → {name, content}[])
for (const mem of data.memories) {
  if (mem.files?.length && typeof mem.files[0] === "string") {
    mem.files = (mem.files as unknown as string[]).map((f) => ({
      name: f,
      content: "",
    }));
  }
}

Architecture

Data Sources

Overview

Core Types

DashboardData

StatsCache

SessionMeta

DailyActivity

DailyModelTokens

ModelUsage

HistoryEntry

ProjectMemory

AccountInfo

SessionMessage

Data Relationships

Export JSON Format

Source Files on Disk

stats-cache.json

session-meta/*.json

history.jsonl

memory/*.md

<session>.jsonl

statsig cache

Backward Compatibility

Build docs developers (and LLMs) love

Architecture

Data Sources

​Overview

​Core Types

​DashboardData

​StatsCache

​SessionMeta

​DailyActivity

​DailyModelTokens

​ModelUsage

​HistoryEntry

​ProjectMemory

​AccountInfo

​SessionMessage

​Data Relationships

​Export JSON Format

​Source Files on Disk

stats-cache.json

session-meta/*.json

history.jsonl

memory/*.md

<session>.jsonl

statsig cache

​Backward Compatibility

Build docs developers (and LLMs) love

Overview

Core Types

DashboardData

StatsCache

SessionMeta

DailyActivity

DailyModelTokens

ModelUsage

HistoryEntry

ProjectMemory

AccountInfo

SessionMessage

Data Relationships

Export JSON Format

Source Files on Disk

Backward Compatibility