tokenleak 1.2.0 → 1.3.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:
@@ -93,6 +111,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 +139,54 @@ 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
+```
+
+- Getting a Cursor session token:
+
+  The exact Cursor UI may change, but this flow works when the token is not exposed directly in settings:
+
+  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.
+
+- 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 --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 +215,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
 
@@ -325,6 +398,7 @@ 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 +413,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 |
@@ -356,7 +431,7 @@ Subcommands:
 | `--version` |  |  | Print version information |
 | `--help` |  |  | Print usage information |
 
-## Supported providers
+## Provider details
 
 ### Claude Code
 
@@ -380,6 +455,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 +638,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:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenleak",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Visualise your AI coding-assistant token usage across providers — heatmaps, dashboards, and shareable cards.",
   "type": "module",
   "bin": {