tokenleak 1.3.0 → 2.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 See where your AI tokens actually go. Tokenleak reads usage data from **Claude Code**, **Codex**, **Cursor**, **Pi (`pi-mono`)**, and **OpenCode**, then renders terminal dashboards, heatmaps, compare reports, explain/focus reports, and shareable image cards from the CLI.
 
-![Tokenleak preview card](./docs/preview.png)
+![Tokenleak OpenTUI overview](./docs/tui-overview.png)
 
 ## Overview
 
@@ -39,18 +39,19 @@ npx tokenleak --help
 ```
 
 After installing, run `tokenleak` in your terminal. It auto-detects supported providers from their local logs.
-In an interactive TTY, plain `tokenleak` opens a launcher where you can:
-
-- render the standard terminal dashboard
-- open a tabbed terminal dashboard
-- export JSON, SVG, or PNG
-- build compare reports
-- run explain reports for a specific day
-- run focus reports for deep-work sessions
-- inspect richer analytics such as model efficiency, cache ROI, session/project drill-downs, and attribution clusters
-- start the local live dashboard
-- launch the interactive AI Wrapped presentation in a browser
-- inspect provider availability and aliases
+In an interactive TTY, plain `tokenleak` launches a full-screen TUI dashboard with 8 views:
+
+- **Overview** — heatmap, stats, providers, and top models
+- **Matrix** — 4-page deep-dive with activity patterns, cache economics, sessions, model efficiency, attribution, and cache ROI by model
+- **Advisor** — model efficiency recommendations with projected savings
+- **Focus** — deep-work session rankings scored by duration, density, and streaks
+- **Explain** — narrative day-by-day usage breakdown
+- **Compare** — side-by-side period comparison with deltas
+- **Export** — save PNG, Wrapped PNG, or launch a live server
+- **Wrapped** — Spotify-Wrapped-style stats card with achievements and usage breakdown
+- **Replay** — chronological session timeline with flow blocks, pulse chart, and flow/think ratio
+
+Use `tokenleak --legacy` to open the classic interactive launcher instead.
 
 ### From source
 
@@ -68,10 +69,13 @@ bun dist/tokenleak.js
 ## Usage
 
 ```bash
-# Open the interactive launcher (TTY only)
+# Open the TUI dashboard (TTY only)
 tokenleak
 
-# Skip the launcher and render directly with flags
+# Open the classic interactive launcher
+tokenleak --legacy
+
+# Skip the TUI and render directly with flags
 tokenleak --format terminal
 
 # Start the local live dashboard server
@@ -107,6 +111,10 @@ tokenleak -o card.png
 tokenleak explain 2026-03-10
 tokenleak explain 2026-03-10 --format json
 
+# Replay a day's session timeline
+tokenleak replay
+tokenleak replay 2026-03-10 --format json
+
 # Rank deep-work sessions
 tokenleak focus
 tokenleak focus --provider codex --days 30
@@ -120,7 +128,7 @@ tokenleak --list-providers
 
 ### Analysis commands
 
-Tokenleak ships two dedicated investigation commands in addition to the main dashboard flow:
+Tokenleak ships three dedicated investigation commands in addition to the main dashboard flow:
 
 ```bash
 # Explain what drove a specific day
@@ -134,10 +142,17 @@ tokenleak focus --days 30
 
 # Focus report as JSON
 tokenleak focus --format json --provider pi --output focus.json
+
+# Replay today's session timeline
+tokenleak replay
+
+# Replay a specific day with JSON output
+tokenleak replay 2026-03-10 --format json --output replay.json
 ```
 
 - `tokenleak explain <date>` builds a narrative day report with top providers, sessions, projects, models, and anomaly flags.
 - `tokenleak focus` ranks sessions by a deep-work score derived from duration, token density, and project streak.
+- `tokenleak replay [date]` shows a chronological timeline of all sessions for a day, clustering events into flow blocks with a pulse chart and flow/think ratio. Defaults to today.
 
 ### Cursor commands
 
@@ -150,18 +165,19 @@ tokenleak cursor accounts --json
 tokenleak cursor switch work
 tokenleak cursor logout --name work
 tokenleak cursor logout --all --purge-cache
+tokenleak cursor reset
 ```
 
 - Getting a Cursor session token:
 
-  The exact Cursor UI may change, but this flow works when the token is not exposed directly in settings:
+  The exact browser wording may vary, but the reliable source of truth is the `WorkosCursorSessionToken` cookie:
 
   1. Open Cursor and sign in.
   2. Open `https://www.cursor.com/settings`.
-  3. Open your browser developer tools, then go to the Network tab.
-  4. Refresh the settings page.
-  5. Inspect a request sent to `cursor.com` and copy the session token from the authenticated request headers or cookies.
-  6. Paste that token into `tokenleak cursor login --name <label>` when prompted.
+  3. Open your browser developer tools.
+  4. Go to `Application` (or `Storage`) -> `Cookies` -> `https://www.cursor.com`.
+  5. Copy the value of the `WorkosCursorSessionToken` cookie.
+  6. Paste that token into `tokenleak cursor login --name <label>` when prompted, or into the TUI setup modal after pressing `c`.
 
 - Local checkout flow:
 
@@ -183,6 +199,7 @@ bun packages/cli/dist/cli.js --provider cursor --format json
 - Normal dashboard/report runs auto-refresh Cursor cache when you are logged in and Cursor is requested or available.
 - If refresh fails but cached CSVs exist, Tokenleak falls back to the cached data.
 - `tokenleak cursor status` only validates the saved session token. It does not mark Cursor as available by itself.
+- `tokenleak cursor reset` clears saved Cursor credentials and the local Cursor cache so you can re-test the in-TUI setup flow from a clean state.
 - `tokenleak --list-providers` reports whether local provider data exists. For Cursor, that means `cursor-cache/usage*.csv` must already be present.
 - If `cursor status` is valid but `--list-providers` still shows Cursor as unavailable, run `tokenleak --provider cursor` once to sync the cache, then rerun `--list-providers`.
 - Cursor session tokens are stored in plaintext at `~/.config/tokenleak/cursor-credentials.json` (or under `TOKENLEAK_CURSOR_DIR`) with local-only file permissions.
@@ -265,6 +282,10 @@ When you use `--format png` or `--format svg`, Tokenleak enables expanded compar
 
 Generate a Spotify-Wrapped-style story card as a tall PNG image showing your AI coding stats, streaks, model usage, habits, achievements, and more.
 
+Current wrapped card generated from the latest Tokenleak build:
+
+![Tokenleak AI Wrapped card](./docs/wrapped-card.png)
+
 ```bash
 # Generate your wrapped card (dark theme, opens automatically)
 tokenleak --format wrapped --open
@@ -280,7 +301,7 @@ The wrapped card includes 12 sections: title, big numbers, streak story, top mod
 
 Achievements are computed from your actual data — earn badges like Streak Master (30+ day streak), Cache Master (>50% hit rate), Night Owl (>40% usage 10pm-6am), Power User (>10k avg daily tokens), and more.
 
-The interactive launcher also includes Wrapped as option `3` with a guided setup flow.
+The TUI dashboard includes a Wrapped view (press `8` or arrow to it). The classic launcher (`tokenleak --legacy`) also offers a guided Wrapped setup flow.
 
 ### Wrapped Live
 
@@ -297,9 +318,11 @@ tokenleak --wrapped-live --days 365 --claude
 tokenleak --wrapped-live --provider claude-code,codex
 ```
 
-The presentation uses the same 12 sections as the static wrapped card but rendered as navigable slides with an obsidian-and-gold design. Use arrow keys, click the nav buttons, or swipe on touch devices to move between slides.
+`tokenleak --format wrapped` is the static export path: it writes a tall PNG you can attach to docs, posts, or issues. `tokenleak --wrapped-live` uses the same underlying stats, but serves them as a browser deck that is better for demos, screenshares, and walking through each section interactively.
+
+The Wrapped Live server starts on `http://localhost:3456` and automatically increments to the next free port if `3456` is already taken. The presentation uses the same 12 sections as the static wrapped card but rendered as navigable slides with an obsidian-and-gold design. Use arrow keys, click the nav buttons, or swipe on touch devices to move between slides.
 
-The interactive launcher includes Wrapped Live as option `4`.
+The classic launcher (`tokenleak --legacy`) includes Wrapped Live as a menu option.
 
 ### Model Efficiency Advisor
 
@@ -372,19 +395,48 @@ tokenleak --format json --upload gist
 
 ## Interactive modes
 
-### Launcher
-
-In a real TTY, `tokenleak` opens a launcher instead of rendering immediately. You can move with arrow keys, use number shortcuts, inspect the exact command preview before running it, and stay inside the same session after each command finishes.
+### TUI dashboard (default)
 
-### Tabbed terminal dashboard
+In a real TTY, `tokenleak` launches a full-screen terminal dashboard built with [@opentui/core](https://www.npmjs.com/package/@opentui/core). The TUI provides 8 views with keyboard and mouse navigation:
 
-The launcher can open a full-screen terminal dashboard with:
+Latest OpenTUI screenshots from the current dashboard build:
 
-- time ranges: `7d`, `30d`, `90d`, `365d`
-- metric tabs: `overview`, `sess`, `tok`, `model`, `cwd`, `dow`, `tod`
-- keyboard navigation for scrolling and switching views
-
-This mode uses event-level data when available, so session, token, project, attribution, model-efficiency, and hour-of-day views are most useful for providers that include session metadata in their local logs.
+| Overview | Matrix (page 4) |
+| --- | --- |
+| ![Overview view](./docs/tui-overview.png) | ![Matrix view](./docs/tui-matrix.png) |
+| Advisor | Focus |
+| ![Advisor view](./docs/tui-advisor.png) | ![Focus view](./docs/tui-focus.png) |
+| Explain | Compare |
+| ![Explain view](./docs/tui-explain.png) | ![Compare view](./docs/tui-compare.png) |
+| Export | Wrapped |
+| ![Export view](./docs/tui-export.png) | ![Wrapped view](./docs/tui-wrapped.png) |
+
+| Key | Action |
+| --- | --- |
+| `←` / `→` | Switch between views |
+| `Tab` / `>` | Next time period (1D → 7D → 30D → 90D → ALL) |
+| `Shift+Tab` / `<` | Previous time period |
+| `1`–`8` | Jump directly to a view |
+| `j` / `k` | Scroll up/down in scrollable views |
+| `[` / `]` | Matrix page navigation (in Matrix view) |
+| `h` / `l` | Previous/next day (in Explain view) |
+| `s` | Toggle sort mode (in Overview) |
+| `r` | Refresh data |
+| `c` | Open Cursor setup when the dashboard shows a Cursor auth/sync banner |
+| `?` | Help overlay |
+| `q` | Quit |
+
+When Cursor needs setup, re-authentication, or a cache retry, the TUI shows a contextual banner. Press `c` to open the built-in Cursor setup flow, paste a session token, validate it, and sync usage CSVs without leaving the dashboard.
+
+The Matrix view spans 4 pages:
+1. Overview + time windows + providers + top models
+2. Hour-of-day, day-of-week, I/O breakdown, monthly burn
+3. Cache economics, cache ROI, session metrics, top projects
+4. Model efficiency, attribution clusters, top sessions, cache ROI by model
+
+### Classic launcher
+
+`tokenleak --legacy` opens the previous interactive launcher with a numbered menu, command preview, and guided setup flows for exports, wrapped cards, and the live dashboard.
 
 ### Live dashboard
 
@@ -392,14 +444,15 @@ This mode uses event-level data when available, so session, token, project, attr
 
 ## All flags
 
-When you run bare `tokenleak` in a real terminal, the launcher shows these flags in-app before you run anything.
+When you run bare `tokenleak` in a real terminal, the TUI dashboard launches. Pass flags to skip the TUI and render directly.
 
 Subcommands:
 
 - `tokenleak explain <date>` supports `--format terminal|json`, `--output`, `--width`, and the standard provider filters.
 - `tokenleak focus` supports `--format terminal|json`, `--output`, `--width`, and the standard provider/date filters.
+- `tokenleak replay [date]` supports `--format terminal|json`, `--output`, `--width`, and the standard provider filters. Date defaults to today.
 - `tokenleak cursor --help` prints the Cursor auth/cache command help text.
-- `tokenleak explain --help` and `tokenleak focus --help` print the subcommand-specific help text.
+- `tokenleak explain --help`, `tokenleak focus --help`, and `tokenleak replay --help` print the subcommand-specific help text.
 
 | Flag | Alias | Default | Description |
 | --- | --- | --- | --- |
@@ -426,6 +479,7 @@ Subcommands:
 | `--live-server` | `-L` | `false` | Start the local browser dashboard |
 | `--wrapped-live` |  | `false` | Start the interactive AI Wrapped presentation in a browser |
 | `--advisor` |  | `false` | Run the model efficiency advisor |
+| `--legacy` |  | `false` | Open the classic interactive launcher instead of the TUI |
 | `--no-color` |  | `false` | Strip ANSI escape codes from terminal output |
 | `--no-insights` |  | `false` | Hide terminal insights |
 | `--version` |  |  | Print version information |
@@ -568,10 +622,12 @@ The dedicated analysis commands also support JSON output:
 ```bash
 tokenleak explain 2026-03-10 --format json
 tokenleak focus --format json
+tokenleak replay 2026-03-10 --format json
 ```
 
-- `tokenleak explain ... --format json` returns an explain report with headline, summary bullets, evidence tables, and anomaly flags.
-- `tokenleak focus ... --format json` returns a ranked focus report with deep-work scores, durations, densities, streaks, and rationales per session.
+- An explain report (`tokenleak explain ... --format json`) includes a headline, summary bullets, evidence tables for providers/models/sessions, and anomaly flags.
+- `tokenleak focus ... --format json` produces a ranked focus report with deep-work scores, durations, token densities, project streaks, and per-session rationales.
+- Use `tokenleak replay ... --format json` to get a replay report containing flow blocks, a token velocity time series, model switch annotations, and a day summary with flow/think ratio.
 
 When `--compare` is used with `--format json`, the output is a compare payload with:
 
@@ -743,12 +799,13 @@ tokenleak/
     core/           Shared types, constants, aggregation engine
     registry/       Provider parsers and model pricing
     renderers/      JSON, SVG, PNG, and terminal output
+    tui/            Full-screen TUI dashboard (default interactive mode)
     cli/            CLI entrypoint and config handling
     mcp/            MCP server for AI assistant integration
   scripts/
     build-npm.ts    Bundles CLI for npm publishing
   dist/
-    tokenleak.js    Bundled CLI (generated)
+    tokenleak       Bundled CLI (generated)
 ```
 
 ## Contributing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenleak",
-  "version": "1.3.0",
+  "version": "2.1.0",
   "description": "Visualise your AI coding-assistant token usage across providers — heatmaps, dashboards, and shareable cards.",
   "type": "module",
   "bin": {
@@ -10,7 +10,8 @@
     "tokenleak"
   ],
   "dependencies": {
-    "sharp": "^0.34.0"
+    "sharp": "^0.34.0",
+    "@opentui/core": "^0.1.88"
   },
   "engines": {
     "bun": ">=1.0.0"