Forensic token analyzer for Claude Code.

ccusage tells you how much you spent. ctok tells you why.

---

What is ctok?

ctok is a 100% local, single-binary tool that parses your ~/.claude/projects/ JSONL session files, indexes them into a SQLite cache, and serves a rich, interactive dashboard.

Answer questions like:

• Which project is burning the most tokens this week?
• Which session drifted the context window into expensive territory?
• Which tool / MCP server / subagent is bleeding tokens?
• Where are my cache breaks happening — and why?
• How does my cost split across models over time?

No telemetry. No cloud. No LLM calls. Just your JSONL files → SQLite → browser.

Features

Dashboard Overview — KPI tiles (total cost, tokens, cache hit ratio, sessions), daily cost stacked area chart by model, cost-by-model donut, top recommendations at a glance.

16 Forensic Views — Daily totals, projects, sessions, models, cache hit ratio, cache breaks, tokens by tool/MCP/skill/subagent, system reminder costs, top expensive messages/sessions/tools.

Interactive Charts — ECharts visualizations on every view: stacked area, donut, horizontal bar, scatter plots, session waterfall with cumulative cost overlay. Dark/light theme, zoom, tooltips.

Rules Engine — 6 built-in rules that analyze your sessions and surface actionable recommendations: oversized CLAUDE.md, unused skills, heavy MCP instructions, cache breakers, repeated large reads, model mismatch.

Live Mode — ctok serve watches your Claude projects directory, re-indexes on file changes, and pushes updates to the dashboard via WebSocket. See your costs update in real-time as you work.

Sortable DataTables — Click any numeric column header to sort. All views show raw data alongside charts.

Global Filters — Period picker (7d/30d/90d/all), persisted in localStorage. All views auto-refetch when filters change.

Quickstart

Requirements: Go 1.25+, Node 20+, npm, make.

git clone https://github.com/jamyouss/ctok.git
cd ctok

# Build frontend + Go binary in one shot
make build

# One-shot: index + dashboard (opens browser automatically)
./bin/ctok

# Live mode: watch for changes + auto-refresh
./bin/ctok serve

CLI Commands

Command	What it does
ctok	Index → serve dashboard → exit
ctok serve	Watch mode — live re-index + WebSocket updates
ctok rebuild	Force full re-index from scratch

Useful Flags

Flag	Default	Description
--port	17389	HTTP port
--bind	127.0.0.1	Bind address (loopback by default)
--claude-dir	~/.claude/projects	Claude Code session directory
--db	~/.ctok/index.db	SQLite index path
--no-open	—	Don't auto-launch the browser
-v / -q	—	Verbose / quiet

Architecture

~/.claude/projects/<encoded>/<session>.jsonl   ← source of truth (append-only)
                    │
                    ▼
            internal/parser           stream JSONL, extract structured messages
                    │
                    ▼
            internal/store            SQLite index (~/.ctok/index.db)
                    │
            ┌───────┴───────┐
            ▼               ▼
    internal/aggregator   internal/rules      forensic views + recommendations
            │               │
            └───────┬───────┘
                    ▼
            internal/api              HTTP + WebSocket
                    │
                    ▼
            web/ (Vue 3 SPA)          embedded via go:embed

Key properties:

• JSONL files are the only source of truth. The SQLite index is a reconstructible cache — rm ~/.ctok/index.db && ctok rebuild always works.
• Single static binary. Parser, store, aggregators, rules, API, watcher, and embedded frontend — all in one bin/ctok.
• Pure Go SQLite (modernc.org/sqlite) — no CGO, clean cross-compilation.
• Incremental indexing. Only parses new data since last run. Full re-index on demand with ctok rebuild.

Tech Stack

Layer	Choice
Backend	Go 1.25, chi v5, modernc.org/sqlite, fsnotify, coder/websocket
CLI	spf13/cobra
Frontend	Vue 3, TypeScript (strict), Vite, Tailwind v4, Pinia, VueUse, shadcn-vue, ECharts
Build	make, go build, vue-tsc + vite build, go:embed

Development

# Backend (go run, watches nothing — restart manually)
make dev-back        # go run ./cmd/ctok serve --port 17389 --no-open

# Frontend (Vite dev server, HMR, /api proxied to backend)
make dev-front       # cd web && npm run dev

# Tests
make test            # go test -race ./...
make lint            # go vet ./...

Philosophy

• Dark mode by default. Dense, technical UI. Comparable to k9s, lazygit, Grafana.
• Your data stays local. Nothing leaves 127.0.0.1. No analytics, no telemetry, no phone-home.
• Rebuildable. Delete the SQLite DB, rebuild — always the same output.
• Boring tech, sharp focus. Go + Vue + SQLite. The value is in the forensics.

Non-goals

• Mobile / responsive UI
• Multi-user or team features
• Cloud-hosted variant
• Multi-LLM support (Claude Code-specific by design)

License

MIT