tokenleak 1.3.0 → 2.0.0

package/README.md

@@ -39,18 +39,18 @@ 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
+
+Use `tokenleak --legacy` to open the classic interactive launcher instead.
 
 ### From source
 
@@ -68,10 +68,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
@@ -150,18 +153,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 +187,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.
@@ -280,7 +285,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
 
@@ -299,7 +304,7 @@ 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.
 
-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 +377,36 @@ 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:
-
-- 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.
+| 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,7 +414,7 @@ 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:
 
@@ -426,6 +448,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 |
@@ -743,12 +766,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.0.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"