tokenleak 1.2.0 → 2.0.0

package/README.md

@@ -1,9 +1,27 @@
 # Tokenleak
 
-See where your AI tokens actually go. Tokenleak reads local usage logs from **Claude Code**, **Codex**, **Pi (`pi-mono`)**, and **OpenCode**, then renders terminal dashboards, heatmaps, compare reports, explain/focus reports, and shareable image cards from the CLI.
+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)
 
+## Overview
+
+Tokenleak auto-detects supported providers from their local logs and storage. This is the quick scan of where it looks before it renders dashboards, reports, and images:
+
+| Client | Local data location | Provider key and aliases | Supported |
+| ------ | ------------------- | ------------------------ | --------- |
+| Claude Code | `~/.claude/projects/**/*.jsonl` | `claude-code`, `anthropic`, `claude`, `claudecode` | Yes |
+| Codex | `~/.codex/sessions/**/*.jsonl` | `codex`, `openai` | Yes |
+| Cursor | `~/.config/tokenleak/cursor-cache/usage*.csv` after `tokenleak cursor login` | `cursor`, `cursor-ide`, `cursoride` | Yes |
+| OpenCode | `~/.local/share/opencode/storage/message/<session>/*.json` or `~/.config/opencode/storage/message/<session>/*.json`<br />Legacy: `~/.opencode/opencode.db`, `~/.opencode/sessions.db`, `~/.opencode/sessions/*.json` | `open-code`, `opencode`, `open_code` | Yes |
+| Pi (`pi-mono`) | `~/.pi/agent/sessions/**/*.jsonl` | `pi`, `pi-mono` | Yes |
+
+- Use `CLAUDE_CONFIG_DIR` to override the Claude Code base directory.
+- Use `CODEX_HOME` to override the Codex base directory.
+- Use `TOKENLEAK_CURSOR_DIR` to override the Cursor credentials/cache directory.
+- Use `PI_CODING_AGENT_DIR` to override the Pi base directory.
+- See [Provider details](#provider-details) for the parser behavior and per-provider notes.
+
 ## Install
 
 Install Tokenleak with the package manager you already use:
@@ -21,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
 
@@ -50,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
@@ -93,6 +114,9 @@ tokenleak explain 2026-03-10 --format json
 tokenleak focus
 tokenleak focus --provider codex --days 30
 
+# Authenticate Cursor and sync its local cache
+tokenleak cursor login --name work
+
 # Show registered providers, availability, and aliases
 tokenleak --list-providers
 ```
@@ -118,6 +142,56 @@ tokenleak focus --format json --provider pi --output focus.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.
 
+### Cursor commands
+
+Use these commands to manage Cursor authentication and the local cache that Tokenleak reads:
+
+```bash
+tokenleak cursor login --name work
+tokenleak cursor status
+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 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.
+  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:
+
+```bash
+# Build once from the repo root
+bun install
+bun run build
+
+# Validate the saved Cursor session token
+bun packages/cli/dist/cli.js cursor status
+
+# Trigger the first Cursor cache sync and show Cursor-only usage
+bun packages/cli/dist/cli.js --provider cursor --format terminal
+
+# Inspect raw Cursor data
+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.
+
 ### Date filtering
 
 By default, Tokenleak shows the last **90 days** of usage.
@@ -146,18 +220,22 @@ tokenleak --provider claude-code
 # Only Codex
 tokenleak --provider codex
 
+# Only Cursor
+tokenleak --provider cursor
+
 # Only Pi
 tokenleak --provider pi
 
 # Multiple providers (comma-separated)
-tokenleak --provider claude-code,codex,pi
+tokenleak --provider claude-code,codex,cursor,pi
 
 # Provider aliases are supported too
-tokenleak --provider anthropic,openai,pi-mono
+tokenleak --provider anthropic,openai,cursor-ide,pi-mono
 
 # Shortcut flags
 tokenleak --claude
 tokenleak --codex
+tokenleak --cursor
 tokenleak --pi
 tokenleak --open-code
 
@@ -207,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
 
@@ -226,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
 
@@ -299,19 +377,36 @@ tokenleak --format json --upload gist
 
 ## Interactive modes
 
-### Launcher
+### TUI dashboard (default)
 
-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.
+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:
 
-### Tabbed terminal dashboard
-
-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
 
@@ -319,12 +414,13 @@ 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 cursor --help` prints the Cursor auth/cache command help text.
 - `tokenleak explain --help` and `tokenleak focus --help` print the subcommand-specific help text.
 
 | Flag | Alias | Default | Description |
@@ -339,6 +435,7 @@ Subcommands:
 | `--provider` | `-p` | auto | Filter to specific provider(s), comma-separated |
 | `--claude` |  | `false` | Shortcut for `--provider claude-code` |
 | `--codex` |  | `false` | Shortcut for `--provider codex` |
+| `--cursor` |  | `false` | Shortcut for `--provider cursor` |
 | `--pi` |  | `false` | Shortcut for `--provider pi` |
 | `--open-code` |  | `false` | Shortcut for `--provider open-code` |
 | `--all-providers` |  | `false` | Ignore provider filters and use every available provider |
@@ -351,12 +448,13 @@ 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 |
 | `--help` |  |  | Print usage information |
 
-## Supported providers
+## Provider details
 
 ### Claude Code
 
@@ -380,6 +478,19 @@ Reads JSONL session logs from the Codex sessions directory. Parses `response` ev
 | **Provider name** | `codex`                               |
 | **Aliases**       | `openai`                              |
 
+### Cursor
+
+Reads Cursor usage CSV exports from the local Tokenleak cache. The cache is populated by authenticating with `tokenleak cursor login`, after which normal runs auto-refresh the CSVs when possible.
+
+`tokenleak cursor status` confirms that your saved session token is valid. Cursor only becomes `[available]` in `tokenleak --list-providers` after the local cache has at least one `usage*.csv` file, usually after the first `tokenleak --provider cursor` run.
+
+|                   |                                                       |
+| ----------------- | ----------------------------------------------------- |
+| **Data location** | `~/.config/tokenleak/cursor-cache/usage*.csv`         |
+| **Override**      | Set `TOKENLEAK_CURSOR_DIR` environment variable       |
+| **Provider name** | `cursor`                                              |
+| **Aliases**       | `cursor-ide`, `cursoride`                             |
+
 ### OpenCode
 
 Reads usage data from current OpenCode message storage when available. Falls back to legacy SQLite databases or legacy JSON session files.
@@ -550,11 +661,12 @@ All fields are optional. Only include the ones you want to override.
 | `TOKENLEAK_MAX_JSONL_RECORD_BYTES` | `10485760` (10 MB) | Max size of a single JSONL record before it is rejected |
 | `CLAUDE_CONFIG_DIR` | `~/.claude` | Claude Code configuration directory |
 | `CODEX_HOME` | `~/.codex` | Codex home directory |
+| `TOKENLEAK_CURSOR_DIR` | `~/.config/tokenleak` | Cursor credentials/cache root (`cursor-credentials.json`, `cursor-cache/`) |
 | `PI_CODING_AGENT_DIR` | `~/.pi/agent` | Pi coding agent directory (sessions live under `sessions/`) |
 
 ## What Tokenleak tracks
 
-Tokenleak reads your **local** logs only. It does not send usage data anywhere unless you explicitly use a sharing feature such as `--upload gist`.
+Tokenleak reads your **local** logs and caches. For Cursor, Tokenleak can also fetch fresh usage CSVs from Cursor's API after you authenticate with `tokenleak cursor login`; that network step only happens for Cursor and only to refresh the local cache.
 
 For each day of usage, it tracks:
 
@@ -654,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.2.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"