xiaoqi-token-stats

Token Usage Statistics

Scan ~/.claude/projects/ for all session JSONL files, providing two visualization views.

Installation

This skill requires Python 3.10+ and no additional dependency packages (implemented purely with the standard library).

After confirming the script path, simply run it. Use Glob to search **/xiaoqi-token-stats/token_stats.py to locate the absolute path.

1. Dashboard (token_stats.py)

Summary cards: totals, daily average, session count, message count
Daily Trend: daily trend line chart (Cache Read / Cache Write / Output layered)
Weekly / Monthly: weekly and monthly stacked bar charts
Token Breakdown: four-type token proportion donut chart + detail cards
Models: model distribution horizontal progress bars
Activity by Hour: 24-hour activity heatmap

python3 /path/to/token_stats.py
python3 /path/to/token_stats.py --since 2026-03-01
python3 /path/to/token_stats.py -o ~/Desktop/token-report.html

Parameter	Description
`--since YYYY-MM-DD`	Start date
`--until YYYY-MM-DD`	End date
`-o PATH`	Output file path (default /tmp/xiaoqi-token-stats.html)
`--no-open`	Do not automatically open the browser

2. Token Calendar (token_calendar.py)

Month calendar view; each date cell shows the day's total Token amount and the consumption distribution by model. Supports month switching, left/right arrow key navigation, and hover to view details.

python3 /path/to/token_calendar.py
python3 /path/to/token_calendar.py --month 2026-03

Parameter	Description
`--month YYYY-MM`	Initial display month (default current month)
`-o PATH`	Output file path (default /tmp/token-calendar.html)
`--no-open`	Do not automatically open the browser

Calendar cell content: date (prominent) · total Token · session/call count · top three model details · model proportion bars. Dates with no data have a dashed border.

Trigger determination

User says "token calendar" or "usage calendar" → run token_calendar.py
Other token statistics requests → run token_stats.py

Number units

All numbers use Chinese units: 亿, 万, 千. Chart axes, tooltips, and card values all follow this rule.

Calendar visual style

Warm light floating card design:

Palette

Variable	Value	Purpose
`--bg`	`#f4f1ec`	Warm paper background
`--card`	`#ffffff`	Floating cards
`--text`	`#1c1917`	Primary text (warm near-black)
`--text-secondary`	`#78716c`	Secondary text
`--text-tertiary`	`#a8a29e`	Auxiliary text
`--accent`	`#d4714f`	Coral accent color
`--border`	`rgba(0,0,0,0.06)`	Default border
`--shadow`	`0 1px 3px rgba(120,100,80,0.06)`	Warm-toned shadow

Fonts

Outfit（Google Fonts）+ PingFang SC / Noto Sans SC CJK fallback. Global tabular-nums align numbers.

Layout rules

Monday start: Monday–Sunday, Saturday and Sunday marked as weekend (coral-colored dates)
Floating card grid: 7-column CSS Grid,gap: 8px, each date with data is an independent white card (border-radius: 14px）
Dates with no data: dashed border (dashed rgba(0,0,0,0.08)), no background
Empty placeholder cell: fully transparent,min-height: 40px
Today highlight: coral border + box-shadow double ring

Daily card content (top to bottom)

Date number (1.1rem / 700 weight, prominent)
Total tokens (1.2rem / 700 weight)
Sessions · Calls (0.68rem secondary text)
Top three model details (color dot + name + usage)
Model share bar (4px stacked color band)

Interaction

Hover: card translateY(-2px) + shadow deepens, model bar scaleY(1.5)
Entrance animation：fadeUp waterfall-style (animation-delay: d * 20ms）
Tooltip: glassmorphism (backdrop-filter: blur(20px)), with full model details + percentages
Keyboard: left and right arrow keys switch months

Page bottom

Donut chart(SVG donut): 180px, shows monthly model share, monthly total displayed in the center
Model legend: two-column card grid, shows the first 6 by default, "Show all" button expands the rest
Each item contains: color dot + model name + usage + percentage

Responsive

< 900px: model details hidden, legend single column
< 600px: model bar hidden, daily cell minimized
Print: hide navigation and footer