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 .

Rust toolchain required. The project uses cargo clippy -- -D warnings for linting.

License

MIT

---

繁體中文

你的 Claude Code 會話可能正在浪費你看不見的 token。 診斷 token 流向、浪費原因，並告訴你該優先修正什麼。

全本地運行 — 解析 ~/.claude JSONL 檔案到 SQLite。資料不離開你的機器。無雲端、無遙測。

功能特色

• 診斷 token 浪費 — 6 種統計異常類型，含嚴重度評分
• 成本審計 — 按會話、專案、全域的費用拆解與月度趨勢
• 趨勢預測 — 日/週/月用量趨勢與燃燒率預測
• 快取優化 — 識別低快取命中率的會話，降低不必要開銷
• 嚴重度排序 — 優先處理影響最大的問題，不只是標記異常
• 自然語言互動 — 用中文直接問：「看看狀況」「這個月花多少」「有異常嗎」

快速開始

# 安裝（自動下載 binary，無需 Rust 工具鏈）
claude plugin install claude-token-analyzer

然後在 Claude Code 中直接問：

> 看看狀況
> 這個月花多少？
> 有異常嗎？
> 分析這個專案
> 用量趨勢

技能一覽

技能	觸發語	功能
cta	"cta"、"分析 token"	智能路由至子技能
cta-health-check	"看看狀況"、"總覽"	一頁式用量摘要
cta-cost-audit	"這個月花多少"、"成本報告"	月度費用明細
cta-anomaly-hunt	"有異常嗎"、"排查"	統計異常掃描
cta-project-review	"專案健檢"	四維度專案分析
cta-trend-watch	"趨勢"、"燃燒率"	用量趨勢分析

歡迎台灣及亞洲開發者試用和回饋！