tokenleak 2.0.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
 
@@ -49,6 +49,7 @@ In an interactive TTY, plain `tokenleak` launches a full-screen TUI dashboard wi
 - **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.
 
@@ -110,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
@@ -123,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
@@ -137,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
 
@@ -270,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
@@ -302,7 +318,9 @@ 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 classic launcher (`tokenleak --legacy`) includes Wrapped Live as a menu option.
 
@@ -381,6 +399,18 @@ tokenleak --format json --upload gist
 
 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:
 
+Latest OpenTUI screenshots from the current dashboard build:
+
+| 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 |
@@ -420,8 +450,9 @@ 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 |
 | --- | --- | --- | --- |
@@ -591,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:
 

package/package.json

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