Why?

Claude Code is powerful — but it's a black box while it runs. You can't see what it's spending, how deep the context is, whether it's looping, or if you're about to hit your quota limit.

claudestat fixes that. It taps into Claude Code's hook system to capture every event, stores it locally in SQLite, and shows you everything in a live dashboard or terminal trace.

• Live tool trace with duration and token cost per call
• Quota guard with configurable kill switch (block new sessions at X%)
• Pattern analyzer: detects loops, Bash overuse, low cache reuse, and more
• Per-session cost breakdown + cache savings + burn rate
• AI-generated weekly usage reports

How it works

Claude Code event
      │
      ▼
  Hook script  (~/.claudestat/hooks/event.js)
       │  POST JSON to daemon
       ▼
  Daemon  (localhost:7337)
       │  stores events in SQLite
       │  enriches with JSONL token data
       │  runs pattern analyzer
       ▼
  Dashboard  (React + Vite, auto-refreshes)
       │
       ▼
  You see everything — live

Windows paths: Claude Code stores its data in ~/.claude/ on all platforms (macOS, Linux, and Windows). ClaudeStat detects the correct path automatically.

Requirements

• Node.js >= 22 (required for node:sqlite)
• Claude Code installed (npm install -g @anthropic-ai/claude-code)

Installation

npm install -g @statforge/claudestat

Using NVM? Make sure you're on your default Node version before installing to avoid stale binary conflicts:

nvm use default && npm install -g @statforge/claudestat

Works with nvm (macOS/Linux) and nvm-windows.

Then wire up the hooks into Claude Code:

claudestat install

This modifies ~/.claude/settings.json to add SessionStart, PreToolUse, PostToolUse, and Stop hooks. A backup is created before any change.

Restart Claude Code after installing so the hooks take effect.

Quick Start

# 1. Start the background daemon
claudestat start

# 2. Open the dashboard in your browser
#    macOS:
open http://localhost:7337
#    Windows:
start http://localhost:7337
#    Linux:
xdg-open http://localhost:7337

# 3. Or watch a live terminal trace
claudestat watch

That's it. Start a Claude Code session and watch the events flow in.

Commands

claudestat watch

Live terminal trace — every tool call as it happens, with duration and token cost.

claudestat watch

  ● Session a3f1bc · my-project · claude-sonnet-4-5

  16:42:01  Bash            342ms    1,240 tok   $0.0018
  16:42:03  Read             89ms      420 tok   $0.0006
  16:42:05  Edit            124ms      890 tok   $0.0013
  16:42:08  Agent (haiku)    2.1s    3,200 tok   $0.0024
  16:42:11  Write            67ms      310 tok   $0.0004

  Context: 42,800 / 200,000 (21%)  │  Session cost: $0.0065  │  🟢 healthy

claudestat top

Ranks your most-used tools by estimated cost, call count, or duration across all sessions.

claudestat top

  🏆 claudestat top — by est. cost (last 30 days)

  #  Tool              Calls    Duration   Est. Cost      %
  ── ───────────────── ──────── ───────────── ───────── ────
   1  Bash              1,240       18.3m     $1.24    38%
   2  Read                890        4.1m     $0.87    27%
   3  Edit                430        2.8m     $0.61    19%
   4  Agent (haiku)       120        9.2m     $0.38    12%
   5  Write               210        1.1m     $0.12     4%

Options: --by cost|count|duration · --days 7|30|90 · --limit N

claudestat status

claudestat status

  Quota 5h   45/50 prompts (90%)  |  reset in 22m
  Plan        MAX5
  Sonnet      3.2h / 5h  this week
  Burn rate   1,240 tok/min

claudestat doctor

Diagnoses common installation problems — useful if claudestat start fails or hooks are not firing.

claudestat doctor

🩺 claudestat doctor
──────────────────────────────────────────────
  ✓  Node.js version (22.17.0)
  ✓  Claude Code installed
  ✓  Hooks installed in Claude Code
  ✓  ~/.claudestat/ data directory exists
  ✓  Hook script deployed (~/.claudestat/hooks/event.js)
  ✓  Daemon running (localhost:7337)
  ✓  Global CLI symlink valid
──────────────────────────────────────────────
  All checks passed — claudestat is healthy!

If a check fails, doctor prints the exact fix command to run.

claudestat export

Export session data to JSON or CSV. Supports date and project filters.

# Export all sessions as JSON to stdout
claudestat export

# Export as CSV to a file
claudestat export csv --output ~/sessions.csv

# Filter by date range
claudestat export json --from 2025-05-01 --to 2025-05-31

# Filter by project name (case-insensitive substring match)
claudestat export csv --project myapp --output myapp-sessions.csv

# Multiple filters combined
claudestat export json --from 2025-05-01 --project claudestat --output may-claudestat.json

Options: --from YYYY-MM-DD · --to YYYY-MM-DD · --project <name> · --output <path>

Each row includes: id, started_at, cwd, project_path, total_cost_usd, total_input_tokens, total_output_tokens, efficiency_score, loops_detected.

claudestat config

# Enable kill switch — block new sessions when quota exceeds 95%
claudestat config --kill-switch true --threshold 95

# Force plan detection instead of auto
claudestat config --plan max5   # pro | max5 | max20 | auto

# Disable daemon rate limit alerts
claudestat config --alerts false

Config is stored at ~/.claudestat/config.json (macOS/Linux) or %USERPROFILE%\.claudestat\config.json (Windows).

Dashboard

The dashboard lives at http://localhost:7337 and has six tabs:

Live

Real-time stream of every tool call in the active session. Shows tool name, duration, and token cost. Agent sub-calls expand into nested traces; Skill invocations collapse into labeled containers.

History

All past sessions sorted by date. Each card shows total tokens (input + cache read + output), USD cost, efficiency score, and detected loops. Click any session to open its full tool trace, DAG view, and a compare panel.

Projects

Grid of every project you've worked on. Shows last active date, total sessions, cost, model usage breakdown (Sonnet / Haiku), and an efficiency progress bar.

Analytics

• 6 KPIs: total cost, tokens, cache savings, hidden loop waste, avg efficiency, session count
• Token/cost trend charts (7 / 30 / 90 days)
• Hours by project
• AI-generated weekly reports (auto-scheduled or on demand)

Top

Tool rankings across all your sessions. Sortable by estimated cost, call count, or duration — with a time filter (7 / 30 / 90 days). Also shows projected weekly and monthly spend based on your recent burn rate.

System

Daemon health, DB size, Node version, config file paths, and memory context.

Configuration reference

Config is stored at ~/.claudestat/config.json (macOS/Linux) or %USERPROFILE%\.claudestat\config.json (Windows) and created automatically on first run.

{
  "killSwitchEnabled": false,
  "killSwitchThreshold": 95,
  "warnThresholds": [70, 85, 95],
  "plan": null,
  "alertsEnabled": true,
  "reportsEnabled": false,
  "reportFrequency": "weekly",
  "reportDay": 1,
  "reportTime": "09:00"
}

You can edit the file directly or use the CLI:

# Enable kill switch at 90% quota
claudestat config --kill-switch true --threshold 90

# Force plan (useful if auto-detect is wrong)
claudestat config --plan max5

Troubleshooting

claudestat start hangs for ~5 seconds Normal — require('express') takes a few seconds on first load. The daemon is starting.

Hooks are not firing / dashboard shows no events Run claudestat doctor — it checks every component and prints the exact fix command. If hooks were installed before upgrading, run claudestat uninstall && claudestat install to refresh.

claudestat command not found after install If using NVM, the binary may point to the wrong Node version:

nvm use default && npm install -g @statforge/claudestat
hash -r claudestat   # macOS/Linux — refresh shell binary cache

Working with multiple projects claudestat tracks every project automatically. The Projects tab groups sessions by working directory. Use claudestat export --project <name> to export data for a specific project.

Approaching rate limit When the daemon is running, it polls quota every 60s and logs a warning to stderr when you cross 70%, 85%, or 95%. On macOS and Linux you also get a desktop notification at the killSwitchThreshold. To see current quota at any time: claudestat status

Kill switch is blocking new sessions The kill switch only activates when killSwitchEnabled: true AND cyclePct >= killSwitchThreshold. To disable: claudestat config --kill-switch false Or wait for the 5h quota window to reset (check time remaining with claudestat status).

node:sqlite experimental warning Expected on Node 22+. claudestat suppresses it automatically — you won't see it in normal use.

Roadmap

Planned for upcoming versions:

• Multi-account support — track usage across multiple Claude accounts
• Slack / webhook alerts — get notified when quota reaches warning thresholds
• VS Code extension — sidebar panel with live stats inside the editor

Have an idea? Open an issue or submit a PR.

Uninstall

claudestat uninstall        # removes hooks from Claude Code settings

# macOS / Linux:
rm -rf ~/.claudestat        # removes DB, config, and PID file

# Windows (PowerShell):
Remove-Item -Recurse -Force "$env:USERPROFILE\.claudestat"

Contributing

claudestat is open source and PRs are welcome.

Whether you want to fix a bug, improve a dashboard view, add a new pattern to the analyzer, or support a new provider — contributions are encouraged.

How to contribute

1. Fork the repository
2. Create a branch: git checkout -b feat/your-feature
3. Make your changes
4. Run the test suite: npm test (208 tests)
5. Open a PR with a clear description of what you changed and why

Good first areas

• Pattern analyzer (src/pattern-analyzer.ts) — add new usage patterns or improve thresholds
• Dashboard components (dashboard/src/components/) — UI improvements, new charts, accessibility
• New commands — ideas like claudestat compare
• Bug reports — open an issue with steps to reproduce and your Node/OS version

Running locally

git clone https://github.com/YOUR_USERNAME/claudestat
cd claudestat
npm install
npm run dev:full   # starts daemon + dashboard hot-reload together
npm test           # run all tests

See CONTRIBUTING.md for full guidelines.

License

MIT — use it, fork it, ship it.