claude-token-analyzer

Claude Token Analyzer

Your Claude Code sessions might be burning tokens you can't see. Diagnoses where your tokens go, why they're wasted, and what to fix first.

Fully local — parses your ~/.claude JSONL files into SQLite. Nothing leaves your machine. No cloud. No telemetry.

English | 繁體中文

Features

• Diagnose token waste — Detects 6 statistical anomaly types (HighCost, LowCacheHitRate, CostInefficient, ExcessiveToolUse, HighTokenUsage, UnusualModelMix) with severity scoring
• Audit costs — Per-session, per-project, and global cost breakdowns with monthly trends
• Forecast spending — Daily/weekly/monthly usage trends with burn-rate projections
• Optimize cache — Identifies sessions with poor cache hit rates that inflate costs
• Prioritize fixes — Severity-scored anomalies so you know what to fix first, not just what's wrong
• Converse naturally — Ask in plain language: "how much did I spend?" or "scan for anomalies"

Quick Start

# Install (binary auto-downloads, no Rust toolchain needed)
claude plugin install claude-token-analyzer

Then just ask in any Claude Code session:

> cta
> how much did I spend this month?
> scan for anomalies
> analyze this project
> show me usage trends

How It Works

~/.claude/projects/**/*.jsonl       Your session logs (never modified)
    → parser.rs                     Extract + deduplicate responses
    → analyzer.rs                   Cost calculation, 10-dimension metrics
    → storage.rs                    Upsert into local SQLite
    → detector.rs                   6-type anomaly detection + severity scoring
    → MCP tools / Skills            You ask, it answers

All processing happens locally. The SQLite database lives under the plugin data directory in plugin mode and falls back to ~/.claude/ in standalone mode. No network calls, no external dependencies at runtime.

Skills

Skill	Trigger Phrases	What It Does
cta	"cta", "analyze tokens"	Routes to the right sub-skill
cta-health-check	"quick check", "overview", "看看狀況"	One-page usage summary
cta-cost-audit	"monthly costs", "cost report", "這個月花多少"	Monthly cost breakdown with model split
cta-anomaly-hunt	"anomalies", "problems", "有異常嗎"	Statistical anomaly scan with drill-down
cta-project-review	"analyze project", "專案健檢"	Four-dimension project analysis
cta-trend-watch	"trends", "burn rate", "趨勢"	Usage trend analysis with forecasting

MCP Tools

Tool	Purpose
sync_db	Sync JSONL session logs to SQLite
analyze_session	10-dimension session analysis
analyze_project	Project-level aggregation with sorting
analyze_global	Cross-project panoramic view
cost_report	Monthly cost report (daily granularity available)
anomaly_scan	6-type anomaly detection with severity scoring
trend_report	Time-series trends (daily/weekly/monthly)

Configuration

Environment variables (all optional):

Variable	Purpose	Default
CTA_DB_PATH	SQLite database location	${CLAUDE_PLUGIN_ROOT}/data/token-analyzer.db or ~/.claude/token-analyzer.db
CTA_PROJECTS_DIR	Session logs directory	${CLAUDE_CONFIG_DIR}/projects or ~/.claude/projects
CTA_ARCHIVE_DIR	Archive directory	${CLAUDE_PLUGIN_ROOT}/data/token-analyzer-archive or ~/.claude/token-analyzer-archive
CTA_PRICING_PATH	Custom pricing TOML	Embedded in binary
CLAUDE_CONFIG_DIR	Claude config root for session logs	unset

Path resolution priority:

• DB/archive: environment variable > plugin mode ($CLAUDE_PLUGIN_ROOT) > standalone mode ($HOME/.claude/)
• Projects: environment variable > Claude config dir ($CLAUDE_CONFIG_DIR/projects) > standalone mode ($HOME/.claude/projects)

Building from Source

git clone https://github.com/li195111/claude-token-analyzer.git
cd claude-token-analyzer
bash scripts/build.sh
# Binary: mcp-server/target/release/cta-mcp-server

# Run tests (106 tests)
cargo test --all-targets --manifest-path mcp-server/Cargo.toml

# Lint
cargo clippy --manifest-path mcp-server/Cargo.toml -- -D warnings

# Launch with plugin loaded
claude --plugin-dir .

Requires: Rust toolchain

Contributing

Issues and PRs welcome! See open issues for starter tasks.

Development setup:

1. Clone the repo and run bash scripts/build.sh
2. Run cargo test --all-targets --manifest-path mcp-server/Cargo.toml to verify
3. Load the plugin locally with claude --plugin-dir .