tokenol 0.1.0__tar.gz

tokenol-0.1.0/.claude/settings.local.json

@@ -0,0 +1,35 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(find /home/ff235/.claude-* -name \".credentials.json\" -exec ls -la {} \\\\;)",
+      "Bash(mount)",
+      "Bash(xargs -I{} head -c 2000 \"{}\")",
+      "Bash(xargs -I{} grep -o '\"thinking\"[^}]*' \"{}\")",
+      "Bash(grep -o '\"type\":\"thinking\",\"thinking\":\"[^\"]\\\\{0,200\\\\}' /home/ff235/.claude/projects/-home-ff235-dev-ReviewSense/3f7581b5-b523-4b68-be8f-c570ec2e30cb/subagents/agent-a35dd56.jsonl)",
+      "Bash(python3 *)",
+      "WebFetch(domain:efficienist.com)",
+      "Bash(node -e \" const fs = require\\('fs'\\); const src = fs.readFileSync\\('/home/ff235/.npm-global/lib/node_modules/ccusage/dist/data-loader-9ESMosno.js', 'utf8'\\); // Search for dedup pattern const idx = src.indexOf\\('seenRequestId'\\) > 0 ? src.indexOf\\('seenRequestId'\\) : src.indexOf\\('Set\\('\\) ; console.log\\('idx:', idx\\); console.log\\(src.substring\\(Math.max\\(0,idx-100\\), idx+600\\)\\); \")",
+      "Bash(node -e \" const fs = require\\('fs'\\); const src = fs.readFileSync\\('/home/ff235/.npm-global/lib/node_modules/ccusage/dist/data-loader-9ESMosno.js', 'utf8'\\); // Find where requestId dedup happens near token counting let idx = 0; while \\(true\\) { idx = src.indexOf\\('requestId', idx+1\\); if \\(idx < 0\\) break; const chunk = src.substring\\(Math.max\\(0,idx-50\\), idx+200\\); if \\(chunk.includes\\('has\\('\\) || chunk.includes\\('add\\('\\) || chunk.includes\\('seen'\\) || chunk.includes\\('skip'\\) || chunk.includes\\('continue'\\)\\) { console.log\\('=== at', idx, '==='\\); console.log\\(chunk\\); console.log\\(\\); } } \")",
+      "Bash(node -e \" const fs = require\\('fs'\\); // Look in the other bundle file const src = fs.readFileSync\\('/home/ff235/.npm-global/lib/node_modules/ccusage/dist/calculate-cost-DWGfKMSD.js', 'utf8'\\); console.log\\('File size:', src.length\\); // Find key patterns for \\(const t of ['requestId', 'seenReq', 'dedup', 'has\\(', 'skip', 'cache_read', 'output_tokens']\\) { const idx = src.indexOf\\(t\\); if \\(idx >= 0\\) { console.log\\('--- found', t, 'at', idx\\); console.log\\(src.substring\\(Math.max\\(0,idx-50\\), idx+200\\)\\); console.log\\(\\); } } \")",
+      "Bash(node *)",
+      "Bash(mkdir -p /tmp/cc-leak-probe)",
+      "Read(//tmp/**)",
+      "Bash(npm pack *)",
+      "Bash(pip install *)",
+      "Bash(python *)",
+      "Bash(tokenol daily *)",
+      "Bash(ruff check *)",
+      "Bash(tokenol sessions *)",
+      "Bash(tokenol live *)",
+      "Bash(git add *)",
+      "Bash(git commit -m ' *)",
+      "Bash(uv run *)",
+      "Bash(uv build *)",
+      "Bash(git commit *)",
+      "Bash(git push *)",
+      "Bash(env *)",
+      "Bash(find ~/.claude* -type d -name \"frontend*\")",
+      "Bash(uv sync *)"
+    ]
+  }
+}

tokenol-0.1.0/.claudesignore

@@ -0,0 +1,12 @@
+# Auto-generated by Claude Wrapper to save Rate Limits
+node_modules/
+.venv/
+venv/
+__pycache__/
+dist/
+*.tar.gz
+*.sqlite
+*.db
+.pytest_cache/
+.cursor/
+.windsurf/

tokenol-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev,serve]"
+      - name: Lint
+        run: ruff check src tests
+      - name: Test
+        run: pytest --cov=tokenol --cov-report=term-missing

tokenol-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+_local/
+*_PLAN.md
+*.plan.md
+RESUME.md
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+.coverage
+htmlcov/

tokenol-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to tokenol are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-04-23
+
+Initial public release.
+
+### Added
+- **CLI** (`tokenol`): `today`, `week`, `window`, `verdicts`, `models`, `projects`,
+  `assumptions`, `doctor`, `watch`, `serve`.
+- **Ingestion**: discovery across `~/.claude*` dirs (honours `CLAUDE_CONFIG_DIR`),
+  JSONL parsing with per-file mtime cache, compound-key deduplication,
+  Windows cwd normalization.
+- **Metrics**: cost rollups with full 4-component billing (input, output,
+  cache_read, cache_creation); 5-hour rolling-window cost; context growth,
+  cache hit rate, cache reuse, cost-per-kW output; session verdicts
+  (`OK`, `CONTEXT_CREEP`, `RUNAWAY_WINDOW`, `TOOL_ERROR_STORM`,
+  `SIDECHAIN_HEAVY`, `DUAL_SESSION_CONFLICT`).
+- **Pattern detection** on session drill-down: `idle_expiry`,
+  `compaction_reinflation`, `context_ceiling_plateau`, `sidechain_explosion`,
+  `tool_error_storm` with severity escalation.
+- **Live dashboard** (`tokenol serve`): SSE-streamed main view with headline
+  tiles (+ last-hour trajectory), hourly / daily charts (linear ↔ log
+  toggle), model and project rollups, recent-activity table.
+- **Drill-down pages**: `/session/<id>` (patterns, cost-per-turn small
+  multiples, per-turn modal), `/project/<cwd>` (cache trend with auto
+  hourly/daily bucketing, verdict distribution with tooltips),
+  `/day/<date>`, `/model/<name>`.
+- **Preferences**: user-editable thresholds and ranges persisted via
+  `XDG_CONFIG_HOME`.
+- **Project grouping**: shortest-proper-ancestor cwd rule generalizes across
+  nested repos without per-user configuration.
+
+### Tested
+- 184 unit + integration tests on Python 3.10 / 3.11 / 3.12.
+
+[0.1.0]: https://github.com/yourorg/tokenol/releases/tag/v0.1.0

tokenol-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: tokenol
+Version: 0.1.0
+Summary: Audit Claude Code JSONL session logs: track cost, cache health, context blow-ups, and 5h-window pressure.
+Project-URL: Homepage, https://github.com/farhanferoz/tokenol
+Project-URL: Issues, https://github.com/farhanferoz/tokenol/issues
+License: MIT
+Keywords: anthropic,audit,claude,cli,cost,tokens
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: duckdb>=0.10
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: serve
+Requires-Dist: fastapi>=0.111; extra == 'serve'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'serve'
+Requires-Dist: watchfiles>=0.21; extra == 'serve'
+Description-Content-Type: text/markdown
+
+# tokenol
+
+Audit [Claude Code](https://claude.com/claude-code) JSONL session logs for cost, cache health, context blow-ups, and 5-hour rate-limit pressure.
+
+`tokenol` parses the session transcripts that Claude Code writes to `~/.claude*/projects/**/*.jsonl` and produces per-day, per-session, per-project, and per-model rollups — plus a live burn-rate view for the active 5-hour window.
+
+## Why tokenol
+
+Claude Code bills you for everything the model reads — input, output, **and** cache creation/reads. When the prompt cache is working, 95%+ of your context tokens cost a tenth of full input price. When it isn't — idle gaps past the 5-minute TTL, context compaction, two sessions in the same repo thrashing each other — the same conversation can cost 10× more without looking any different.
+
+`tokenol` tells you which sessions, projects, and hours did that, and usually why. You run it locally over the JSONL logs Claude Code already writes; nothing is uploaded anywhere.
+
+## Dashboard
+
+![Main dashboard](docs/screenshots/main.jpg)
+
+Session drill-down — pattern detection + cost-per-turn small multiples:
+
+![Session drill-down, top](docs/screenshots/session_top.jpg)
+![Session drill-down, lower panels](docs/screenshots/session_bottom.jpg)
+
+Project page — cache efficiency trend, verdict distribution, top turns:
+
+![Project page](docs/screenshots/project.jpg)
+
+## Install
+
+```bash
+pipx install tokenol
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```bash
+# Daily token / cost aggregates over the last 14 days
+tokenol daily
+
+# Hourly breakdown for today
+tokenol hourly
+
+# Top 10 most expensive sessions in the last 30 days
+tokenol sessions --since 30d --top 10 --sort cost
+
+# Per-project rollup
+tokenol projects
+
+# Live view: burn rate + projected end-of-window cost
+tokenol live --last 20m
+```
+
+All commands scan every JSONL file under `$CLAUDE_CONFIG_DIR` (falling back to the standard `~/.claude*` locations) and deduplicate turns using the same `message.id:requestId` compound key that [ccusage](https://github.com/ryoppippi/ccusage) uses.
+
+### Scanning multiple projects
+
+If you use workspace isolation (one `~/.claude-<project>` directory per repo, pointed at via `CLAUDE_CONFIG_DIR`), `tokenol` by default only sees the currently-active project. Pass **`--all-projects`** (or `-A`) to any command to scan every `~/.claude*` directory and get a cross-project view:
+
+```bash
+# Total spend across every project in the last 14 days
+tokenol daily --since 14d --all-projects
+
+# Which sessions cost the most, globally
+tokenol sessions --since 30d --top 10 -A
+```
+
+You can also set `CLAUDE_CONFIG_DIR` to a colon- or comma-separated list of paths to scan a specific subset.
+
+## Commands
+
+| Command    | What it shows                                                               |
+| ---------- | --------------------------------------------------------------------------- |
+| `daily`    | Per-day tokens (input, output, cache read/creation), cost, turn count       |
+| `hourly`   | Per-hour breakdown for a single day (defaults to today)                     |
+| `live`     | Active 5-hour window burn rate, recent-activity rate, projected final cost  |
+| `sessions` | Per-session detail table with blow-up verdict (RUNAWAY, CONTEXT_CREEP, …)  |
+| `projects` | Per-project rollup grouped by `cwd`                                         |
+| `models`   | Per-model rollup with tool-use counts and error rates                       |
+| `verify`   | Cross-check tokenol totals against `ccusage --json` (if installed)          |
+| `serve`    | Launch a local browser dashboard with live burn-rate gauge and all panels   |
+
+Every command accepts:
+
+- `--since 14d` — lookback window (e.g. `7d`, `30d`, or an ISO date)
+- `--all-projects` / `-A` — scan every `~/.claude*` directory (ignores `CLAUDE_CONFIG_DIR`)
+- `--strict` — exit non-zero if any cost-computation assumption fired
+- `--show-assumptions` — always print the assumption footer
+- `--log-level debug|info|warning`
+
+`tokenol sessions` additionally takes `--sort` (`cost`, `input`, `output`, `cache_read`, `turns`, `max_input`, `duration`) and `--top`.
+
+`tokenol live` takes `--last 20m|2h|30s` and exits non-zero if the projected window cost exceeds the configured reference.
+
+## Live dashboard
+
+```bash
+# Install with dashboard dependencies
+pipx install 'tokenol[serve]'
+
+# Start the dashboard (binds to http://127.0.0.1:8787)
+tokenol serve
+
+# Cross-project view, faster tick, custom reference threshold
+tokenol serve --all-projects --tick 2s --reference 25
+
+# Open browser automatically
+tokenol serve --open
+```
+
+The dashboard updates via SSE as Claude Code writes events to disk. Main page layout (top to bottom):
+
+| Panel | What it shows |
+|---|---|
+| **Topbar** | Today's cost · sessions · output · last-active time; global period selector (Today / 7D / 30D / All) |
+| **Efficiency tiles** | Hit% · $/kW · Ctx · Cache reuse — each with a delta chip vs 7-day median and colour-coded threshold |
+| **Hour By Hour** | Hourly metric timeline with day-picker, metric pills, project/model filters, and click-to-drilldown |
+| **Daily History** | 30-day metric history with 7-day moving average overlay; range pills (7D / 30D / 90D / All) |
+| **Models** | Per-model cost, turns, output, and efficiency metrics; local range override; click row → `/model/<name>` |
+| **Recent Activity** | Active projects in the last 60 min with Ctx used, $/kW, hit%, verdict; sortable; click row → `/project/<cwd>` |
+
+Keyboard shortcuts: `?` Glossary · `/` Find · `,` Settings · `Esc` close/back · `g t` scroll to top · `↑↓ Enter` table row navigation · `← →` chart cursor.
+
+### Efficiency metric glossary
+
+| Metric | Definition | Target |
+|---|---|---|
+| **Hit%** | `cache_read / (cache_read + cache_creation + input)` | ≥ 95% |
+| **$/kW** | `cost × 1000 / output_tokens` — dollars per 1k output tokens | < $0.20 |
+| **Ctx** | `cache_read / output` as N:1 — context tokens read per output token | < 400:1 |
+| **Cache reuse** | `cache_read / cache_creation` as N:1 — low = cache thrashing | > 50:1 |
+| **Ctx used** | Latest turn's visible context ÷ model context window | < 85% |
+
+### Preferences
+
+User preferences (tick cadence and threshold overrides) are saved to:
+
+```
+$XDG_CONFIG_HOME/tokenol/prefs.json   # default: ~/.config/tokenol/prefs.json
+```
+
+Shape:
+
+```json
+{
+  "tick_seconds": 300,
+  "reference_usd": 50.0,
+  "thresholds": {
+    "hit_rate_good_pct": 95,
+    "hit_rate_red_pct": 85,
+    "cost_per_kw_good": 0.20,
+    "cost_per_kw_red": 0.40,
+    "ctx_ratio_red": 400.0,
+    "cache_reuse_good": 50.0,
+    "cache_reuse_red": 20.0
+  }
+}
+```
+
+Reset to defaults via the Settings modal (`POST /api/prefs {"thresholds": "reset"}`).
+
+### Session drill-down
+
+Click any session to open the drill-down page (`/session/<id>`). It shows:
+
+- **What likely went wrong** — automated pattern cards at the top of the page, each with a headline, the measurable signal that triggered it, and a suggested fix. Five patterns are detected:
+
+  | Pattern | Signal |
+  |---|---|
+  | **Idle expiry** | Gap ≥ 1 h between turns + next turn was ≥ 80% cache_creation — the 5-minute prompt-cache TTL expired |
+  | **Compaction re-inflation** | Visible-token count dropped then climbed back to ≥ 80% of the previous peak — compacting but immediately refilling the context |
+  | **Context ceiling plateau** | ≥ 20 consecutive turns at ≥ 90% of the model's context window — paying near-full-context input rates throughout |
+  | **Sidechain explosion** | Sidechain/task-agent work accounts for > 40% of session cost |
+  | **Tool error storm** | > 20% error rate across any 10-turn window |
+
+- **Cost per turn** — stacked bar chart (input / output / cache_read / cache_creation). Toggle "All" or "Top 30" to focus on the most expensive turns. Click any bar to open the per-turn detail modal.
+
+- **Per-turn modal** — cost component breakdown, token counts, tool call results (✓/✗), first 500 chars of the user prompt and assistant preview. Navigate with ← / → or close with Esc.
+
+## What it detects
+
+For every session, `tokenol` computes a blow-up verdict against spec-defined thresholds:
+
+| Verdict (table label)         | Trigger                                                |
+| ----------------------------- | ------------------------------------------------------ |
+| `RUNAWAY_WINDOW` (`runaway`)  | Any 5-hour window costs ≥ \$50                         |
+| `CONTEXT_CREEP` (`ctx-creep`) | Max single-turn input ≥ 500k **and** growth ≥ 2k/turn  |
+| `TOOL_ERROR_STORM` (`tool-errs`) | ≥ 10 tool uses with > 30% error rate                |
+| `SIDECHAIN_HEAVY` (`sidechain`) | Sidechain session costing > \$5                      |
+| `OK` (`ok`)                   | Everything else                                        |
+
+### Daily efficiency columns
+
+The `tokenol daily` report shows these cost/cache efficiency ratios:
+
+| Column | Meaning | Target |
+|---|---|---|
+| `$/kW` | USD per 1,000 output tokens | `< $0.20` |
+| `Ctx` | Context tokens read per output token (N:1) | lower is better |
+| `Cache reuse` | Cache reads per cache-creation token (N:1) | `> 50:1` |
+| `Hit%` | % of context served from prompt cache | `≥ 95%` |
+
+## Pricing
+
+Flat per-model rates (no 1M-token tier surcharge — matches ccusage's default behaviour). The current registry lives in `src/tokenol/metrics/cost.py`. When a turn's model isn't in the registry, `tokenol` records an `UNKNOWN_MODEL_FALLBACK` assumption tag and uses a conservative default; run with `--show-assumptions` or `--strict` to surface these.
+
+See [`docs/METRICS.md`](docs/METRICS.md) for metric definitions and [`docs/ASSUMPTIONS.md`](docs/ASSUMPTIONS.md) for the full list of assumption tags.
+
+## Development
+
+```bash
+git clone https://github.com/farhanferoz/tokenol
+cd tokenol
+uv sync --extra dev
+uv run pytest
+uv run ruff check
+```
+
+## Licence
+
+MIT

tokenol-0.1.0/README.md

@@ -0,0 +1,220 @@
+# tokenol
+
+Audit [Claude Code](https://claude.com/claude-code) JSONL session logs for cost, cache health, context blow-ups, and 5-hour rate-limit pressure.
+
+`tokenol` parses the session transcripts that Claude Code writes to `~/.claude*/projects/**/*.jsonl` and produces per-day, per-session, per-project, and per-model rollups — plus a live burn-rate view for the active 5-hour window.
+
+## Why tokenol
+
+Claude Code bills you for everything the model reads — input, output, **and** cache creation/reads. When the prompt cache is working, 95%+ of your context tokens cost a tenth of full input price. When it isn't — idle gaps past the 5-minute TTL, context compaction, two sessions in the same repo thrashing each other — the same conversation can cost 10× more without looking any different.
+
+`tokenol` tells you which sessions, projects, and hours did that, and usually why. You run it locally over the JSONL logs Claude Code already writes; nothing is uploaded anywhere.
+
+## Dashboard
+
+![Main dashboard](docs/screenshots/main.jpg)
+
+Session drill-down — pattern detection + cost-per-turn small multiples:
+
+![Session drill-down, top](docs/screenshots/session_top.jpg)
+![Session drill-down, lower panels](docs/screenshots/session_bottom.jpg)
+
+Project page — cache efficiency trend, verdict distribution, top turns:
+
+![Project page](docs/screenshots/project.jpg)
+
+## Install
+
+```bash
+pipx install tokenol
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```bash
+# Daily token / cost aggregates over the last 14 days
+tokenol daily
+
+# Hourly breakdown for today
+tokenol hourly
+
+# Top 10 most expensive sessions in the last 30 days
+tokenol sessions --since 30d --top 10 --sort cost
+
+# Per-project rollup
+tokenol projects
+
+# Live view: burn rate + projected end-of-window cost
+tokenol live --last 20m
+```
+
+All commands scan every JSONL file under `$CLAUDE_CONFIG_DIR` (falling back to the standard `~/.claude*` locations) and deduplicate turns using the same `message.id:requestId` compound key that [ccusage](https://github.com/ryoppippi/ccusage) uses.
+
+### Scanning multiple projects
+
+If you use workspace isolation (one `~/.claude-<project>` directory per repo, pointed at via `CLAUDE_CONFIG_DIR`), `tokenol` by default only sees the currently-active project. Pass **`--all-projects`** (or `-A`) to any command to scan every `~/.claude*` directory and get a cross-project view:
+
+```bash
+# Total spend across every project in the last 14 days
+tokenol daily --since 14d --all-projects
+
+# Which sessions cost the most, globally
+tokenol sessions --since 30d --top 10 -A
+```
+
+You can also set `CLAUDE_CONFIG_DIR` to a colon- or comma-separated list of paths to scan a specific subset.
+
+## Commands
+
+| Command    | What it shows                                                               |
+| ---------- | --------------------------------------------------------------------------- |
+| `daily`    | Per-day tokens (input, output, cache read/creation), cost, turn count       |
+| `hourly`   | Per-hour breakdown for a single day (defaults to today)                     |
+| `live`     | Active 5-hour window burn rate, recent-activity rate, projected final cost  |
+| `sessions` | Per-session detail table with blow-up verdict (RUNAWAY, CONTEXT_CREEP, …)  |
+| `projects` | Per-project rollup grouped by `cwd`                                         |
+| `models`   | Per-model rollup with tool-use counts and error rates                       |
+| `verify`   | Cross-check tokenol totals against `ccusage --json` (if installed)          |
+| `serve`    | Launch a local browser dashboard with live burn-rate gauge and all panels   |
+
+Every command accepts:
+
+- `--since 14d` — lookback window (e.g. `7d`, `30d`, or an ISO date)
+- `--all-projects` / `-A` — scan every `~/.claude*` directory (ignores `CLAUDE_CONFIG_DIR`)
+- `--strict` — exit non-zero if any cost-computation assumption fired
+- `--show-assumptions` — always print the assumption footer
+- `--log-level debug|info|warning`
+
+`tokenol sessions` additionally takes `--sort` (`cost`, `input`, `output`, `cache_read`, `turns`, `max_input`, `duration`) and `--top`.
+
+`tokenol live` takes `--last 20m|2h|30s` and exits non-zero if the projected window cost exceeds the configured reference.
+
+## Live dashboard
+
+```bash
+# Install with dashboard dependencies
+pipx install 'tokenol[serve]'
+
+# Start the dashboard (binds to http://127.0.0.1:8787)
+tokenol serve
+
+# Cross-project view, faster tick, custom reference threshold
+tokenol serve --all-projects --tick 2s --reference 25
+
+# Open browser automatically
+tokenol serve --open
+```
+
+The dashboard updates via SSE as Claude Code writes events to disk. Main page layout (top to bottom):
+
+| Panel | What it shows |
+|---|---|
+| **Topbar** | Today's cost · sessions · output · last-active time; global period selector (Today / 7D / 30D / All) |
+| **Efficiency tiles** | Hit% · $/kW · Ctx · Cache reuse — each with a delta chip vs 7-day median and colour-coded threshold |
+| **Hour By Hour** | Hourly metric timeline with day-picker, metric pills, project/model filters, and click-to-drilldown |
+| **Daily History** | 30-day metric history with 7-day moving average overlay; range pills (7D / 30D / 90D / All) |
+| **Models** | Per-model cost, turns, output, and efficiency metrics; local range override; click row → `/model/<name>` |
+| **Recent Activity** | Active projects in the last 60 min with Ctx used, $/kW, hit%, verdict; sortable; click row → `/project/<cwd>` |
+
+Keyboard shortcuts: `?` Glossary · `/` Find · `,` Settings · `Esc` close/back · `g t` scroll to top · `↑↓ Enter` table row navigation · `← →` chart cursor.
+
+### Efficiency metric glossary
+
+| Metric | Definition | Target |
+|---|---|---|
+| **Hit%** | `cache_read / (cache_read + cache_creation + input)` | ≥ 95% |
+| **$/kW** | `cost × 1000 / output_tokens` — dollars per 1k output tokens | < $0.20 |
+| **Ctx** | `cache_read / output` as N:1 — context tokens read per output token | < 400:1 |
+| **Cache reuse** | `cache_read / cache_creation` as N:1 — low = cache thrashing | > 50:1 |
+| **Ctx used** | Latest turn's visible context ÷ model context window | < 85% |
+
+### Preferences
+
+User preferences (tick cadence and threshold overrides) are saved to:
+
+```
+$XDG_CONFIG_HOME/tokenol/prefs.json   # default: ~/.config/tokenol/prefs.json
+```
+
+Shape:
+
+```json
+{
+  "tick_seconds": 300,
+  "reference_usd": 50.0,
+  "thresholds": {
+    "hit_rate_good_pct": 95,
+    "hit_rate_red_pct": 85,
+    "cost_per_kw_good": 0.20,
+    "cost_per_kw_red": 0.40,
+    "ctx_ratio_red": 400.0,
+    "cache_reuse_good": 50.0,
+    "cache_reuse_red": 20.0
+  }
+}
+```
+
+Reset to defaults via the Settings modal (`POST /api/prefs {"thresholds": "reset"}`).
+
+### Session drill-down
+
+Click any session to open the drill-down page (`/session/<id>`). It shows:
+
+- **What likely went wrong** — automated pattern cards at the top of the page, each with a headline, the measurable signal that triggered it, and a suggested fix. Five patterns are detected:
+
+  | Pattern | Signal |
+  |---|---|
+  | **Idle expiry** | Gap ≥ 1 h between turns + next turn was ≥ 80% cache_creation — the 5-minute prompt-cache TTL expired |
+  | **Compaction re-inflation** | Visible-token count dropped then climbed back to ≥ 80% of the previous peak — compacting but immediately refilling the context |
+  | **Context ceiling plateau** | ≥ 20 consecutive turns at ≥ 90% of the model's context window — paying near-full-context input rates throughout |
+  | **Sidechain explosion** | Sidechain/task-agent work accounts for > 40% of session cost |
+  | **Tool error storm** | > 20% error rate across any 10-turn window |
+
+- **Cost per turn** — stacked bar chart (input / output / cache_read / cache_creation). Toggle "All" or "Top 30" to focus on the most expensive turns. Click any bar to open the per-turn detail modal.
+
+- **Per-turn modal** — cost component breakdown, token counts, tool call results (✓/✗), first 500 chars of the user prompt and assistant preview. Navigate with ← / → or close with Esc.
+
+## What it detects
+
+For every session, `tokenol` computes a blow-up verdict against spec-defined thresholds:
+
+| Verdict (table label)         | Trigger                                                |
+| ----------------------------- | ------------------------------------------------------ |
+| `RUNAWAY_WINDOW` (`runaway`)  | Any 5-hour window costs ≥ \$50                         |
+| `CONTEXT_CREEP` (`ctx-creep`) | Max single-turn input ≥ 500k **and** growth ≥ 2k/turn  |
+| `TOOL_ERROR_STORM` (`tool-errs`) | ≥ 10 tool uses with > 30% error rate                |
+| `SIDECHAIN_HEAVY` (`sidechain`) | Sidechain session costing > \$5                      |
+| `OK` (`ok`)                   | Everything else                                        |
+
+### Daily efficiency columns
+
+The `tokenol daily` report shows these cost/cache efficiency ratios:
+
+| Column | Meaning | Target |
+|---|---|---|
+| `$/kW` | USD per 1,000 output tokens | `< $0.20` |
+| `Ctx` | Context tokens read per output token (N:1) | lower is better |
+| `Cache reuse` | Cache reads per cache-creation token (N:1) | `> 50:1` |
+| `Hit%` | % of context served from prompt cache | `≥ 95%` |
+
+## Pricing
+
+Flat per-model rates (no 1M-token tier surcharge — matches ccusage's default behaviour). The current registry lives in `src/tokenol/metrics/cost.py`. When a turn's model isn't in the registry, `tokenol` records an `UNKNOWN_MODEL_FALLBACK` assumption tag and uses a conservative default; run with `--show-assumptions` or `--strict` to surface these.
+
+See [`docs/METRICS.md`](docs/METRICS.md) for metric definitions and [`docs/ASSUMPTIONS.md`](docs/ASSUMPTIONS.md) for the full list of assumption tags.
+
+## Development
+
+```bash
+git clone https://github.com/farhanferoz/tokenol
+cd tokenol
+uv sync --extra dev
+uv run pytest
+uv run ruff check
+```
+
+## Licence
+
+MIT

tokenol-0.1.0/docs/ASSUMPTIONS.md

@@ -0,0 +1,34 @@
+# tokenol Assumptions Catalog
+
+Every heuristic or fallback that tokenol applies is recorded as an `AssumptionTag`.
+These surface in three places:
+- Report footer summary (printed automatically when any fire)
+- `--show-assumptions` flag forces the footer to print even when empty
+- `--log-level debug` emits stderr JSON lines per decision
+- `--strict` mode treats any fired assumption as a fatal error
+
+---
+
+## Assumption Tags
+
+| Tag | Heuristic | Why needed | Error mode |
+|---|---|---|---|
+| `WINDOW_BOUNDARY_HEURISTIC` | 5h window starts at first billable event; runs 5h wall-clock; next event after expiry starts a new window | Anthropic's exact server-side rule isn't published; matches community reverse-engineering | Drifts if Anthropic uses fixed-UTC or overlapping-rolling windows |
+| `UNKNOWN_MODEL_FALLBACK` | Unknown Claude model inherits pricing + context from nearest-known family sibling | No machine-readable pricing feed; new models appear before we update | Warned per model; slight mispricing until registry updated |
+| `DEDUP_PASSTHROUGH` | Events with `null` `message.id` or `null` `requestId` pass through dedup (matches ccusage behavior) | Cannot form the compound hash key | Rare; logged per event |
+| `INTERRUPTED_TURN_SKIPPED` | Assistant messages with no `usage` fields (stop_reason=NONE) excluded from cost | Request never completed; no billing data | None — correctly excludes |
+| `GEMINI_UNPRICED` | Non-Claude models (gemini-*) parsed but not priced | Multi-provider pricing is post-v1 | Cost rows show `—` for these models |
+
+---
+
+## New tags added in Phase 2
+
+`WINDOW_BOUNDARY_HEURISTIC` was defined in Phase 1 but first fired in Phase 2 when `align_windows()` is called. It fires once per `align_windows()` call, not once per turn.
+
+---
+
+## CLI Flags
+
+- `--strict` — refuse any assumption fallback; error out with non-zero exit code.
+- `--show-assumptions` — force the footer to print even if no assumptions fired. Useful for CI output.
+- `--log-level debug` — set Python's root logging level to DEBUG; enables verbose per-decision output.