diff --git a/README.md b/README.md index ad0a6a9..d53ca1e 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,30 @@ -# dsh-plugin-token-heatmap +# dsh-token-heatmap -Visualizes your daily token consumption, prompt intensity, cache hit efficiency, and streaks across all sessions in a 52-week contribution calendar. +> GitHub-style daily token usage heatmap, model analytics, and timeline trends for [DeepSeek Harness](https://github.com/deepseek-ai/dsh). + +

+ Token Heatmap & Overview + Model Usage Breakdown & Trends +

+ +--- + +## Features + +- **52-Week GitHub Contribution Calendar:** 7 rows × 52 columns tracking daily token activity with a smooth monochromatic gradient anchored on DeepSeek's official brand blue (`#3964FE`). +- **Interactive Day Inspector:** Click on any day to slide open an inspection drawer showing every session active on that date, exact timestamps, and token breakdown. +- **Top Model Usage Breakdown:** Real-time distribution showing tokens, percentages, and request steps for every model used across sessions. +- **Token Usage Trends Timeline:** Stacked bar chart comparing daily Billed Tokens vs. Cache Reads, with **14D / 30D / 90D** range filters and hover tooltips. +- **Global & Per-Session Filtering:** Toggle between aggregate global history or inspect token activity for individual sessions. +- **Auto-Expanding Panel:** Smoothly widens the DSH Settings dialog to 1180px so the calendar and charts fit cleanly with zero scrollbars. +- **Session Token Meter Integration:** Injects a clean action button into the in-session token usage dialog to open the heatmap directly from active sessions. +- **High-Performance Parser:** Recursively aggregates local `.jsonl.zstd` logs with timestamp and mtime caching for instant loading. --- ## Installation -Install with a single command via the official DSH CLI (automatically downloads, registers, and activates the bundle in your web profile): +Install with a single command via the official DSH CLI: ```bash dsh plugin --profile web add dsh-token-heatmap @@ -14,7 +32,6 @@ dsh plugin --profile web add dsh-token-heatmap *(To remove later: `dsh plugin --profile web remove dsh-token-heatmap`)* - --- ### Manual Alternative (pnpm) @@ -23,35 +40,33 @@ dsh plugin --profile web add dsh-token-heatmap cd ~/.dsh/profiles/web pnpm add dsh-token-heatmap ``` + Then add `"dsh-token-heatmap"` to `bundles` in `~/.dsh/profiles/web/package.json`. --- -## Features - -- **52-Week GitHub Contribution Calendar:** 7 rows × 52 columns tracking daily token activity with 4-level color intensity. -- **Detailed Summary Cards:** - - **Total Tokens:** Complete volume of input, output, and cached tokens. - - **Cache Hit Ratio:** Percentage of tokens served from KV cache reads. - - **Daily Average & Active Days:** Real workload metrics. - - **Streak Tracker:** Current and longest active day streaks. - - **Peak Day Callout:** Date and token count for your heaviest day. -- **Dual Color Palette:** Switch between **GitHub Emerald** and **DeepSeek Indigo**. -- **Interactive Tooltips:** Hover over any day to see token breakdown (billed input/output vs. cache reads and step counts). -- **Session Token Meter Integration:** Integrates into session stats pills with a *"View 12-Month Activity Heatmap"* button that opens the interactive modal dialog anywhere. -- **High-Performance Parser:** Aggregates zstandard (`.jsonl.zstd`) session logs with timestamp and mtime caching for near-instant rendering. -- **DeepSeek Native Theme:** Automatically adapts to DSH dark and light themes using `--dsw-alias-*` design tokens. - ---- - ## Usage 1. Open the DeepSeek Harness Web GUI (`http://127.0.0.1:3080`). 2. Go to **Settings** (gear icon at the bottom left) → **Token Heatmap**. -3. Or during any session, click on the token stats pill at the bottom of the composer to view token details and tap **"View 12-Month Activity Heatmap →"**. +3. Or during any session, click on the token stats pill at the bottom of the composer and tap **"View Token Usage Heatmap →"**. + +--- + +## Preview Screenshots + +### 1. Overview, Hero Total & Contribution Calendar +

+ DeepSeek Harness Token Heatmap Overview +

+ +### 2. Model Breakdown & Timeline Trends +

+ DeepSeek Harness Model Analytics and Trends +

--- ## License -MIT © [oiupoyt](https://github.com/oiupoyt) +MIT © [oiupoyt](https://git.oiupoyt.space/oiupoyt) diff --git a/assets/preview-overview.jpg b/assets/preview-overview.jpg new file mode 100644 index 0000000..f459b97 Binary files /dev/null and b/assets/preview-overview.jpg differ diff --git a/assets/preview-trends.jpg b/assets/preview-trends.jpg new file mode 100644 index 0000000..3565058 Binary files /dev/null and b/assets/preview-trends.jpg differ