@zhangferry-dev/tokendash 1.4.0 → 1.5.0

package/README.md

@@ -4,22 +4,47 @@ A beautiful, local web dashboard for visualizing your Claude Code, Codex, OpenCl
 
 It runs locally and parses token usage data directly from local session files, presenting it in a clean, interactive React dashboard. No external CLI dependencies required.
 
-![Product Screenshoot](resources/product_screenshoot.png)
+![Web Dashboard](resources/product_screenshoot.png)
 
 ## Features
 
 - **Multi-Agent Support:** View usage for Claude Code, Codex, OpenClaw, and OpenCode.
-- **Direct JSONL Parsing:** Reads `~/.claude/projects/` JSONL files directly — no `ccusage` CLI dependency, 100x faster data loading.
+- **Direct JSONL Parsing:** Reads local session files directly — 100x faster data loading.
 - **Detailed Metrics:** Track total tokens, cost (USD), active days, cache hit rates, and output/input ratio.
 - **Today by Hour:** 24-hour token consumption panel showing hourly breakdown for the current day.
-- **Code Analytics:** Visualize code change trends, tool call frequency, and productivity KPIs (Claude Code & OpenClaw only).
-- **Pricing Transparency:** Toggle Cost metric to see per-model pricing formula and rates.
+- **Code Analytics:** Visualize code change trends, tool call frequency, and productivity KPIs.
 - **Interactive Charts:** Bar/line/area charts with tooltips, model breakdowns, and time range filtering.
 - **24-Hour Heatmap:** Activity distribution by hour and day of week, with timezone awareness.
 - **Model & Project Distribution:** See which models and projects drive your usage.
 - **Persistent Filters:** Your selected time range, project, and metric mode are saved automatically.
-- **macOS Menu Bar App:** Native tray icon with real-time token usage, popover dashboard, and agent filtering — runs silently in the background.
-- **Test Coverage:** Unit tests (Vitest) and E2E tests (Playwright) for reliability.
+
+## macOS Menu Bar App
+
+TokenDash ships as a native macOS menu-bar-only application — no Dock icon, no window clutter. It lives quietly in your status bar and gives you instant access to your AI token usage at a glance.
+
+![macOS Menu Bar](resources/product_menu.png)
+
+**Status Bar Badge**
+- Displays real-time token count (e.g. `1.2K`, `32.0M`) directly in the macOS status bar
+- Updates every 5 seconds automatically
+- Shows cost and cache hit rate in the tooltip on hover
+- Resilient badge: transient network or data errors won't clear your existing badge value
+
+**Popover Dashboard**
+- Click the status bar icon to open a compact popover with today's full breakdown:
+  - Total tokens, input/output/cache metrics at a glance
+  - Hourly consumption bar chart with peak value highlight
+  - Agent filter dropdown (show only Claude Code, Codex, etc.)
+  - Settings: launch at login, check for updates, quit
+- The popover syncs rendered totals back to the status bar badge for maximum accuracy
+
+**Native Integration**
+- Written in Swift (`trayHelper.swift`) for macOS 14+ compatibility
+- Menu-bar-only (`LSUIElement: true`) — no Dock icon, runs silently in the background
+- Dark mode support with automatic theme switching
+- Custom app icon
+- Distributed as a standard macOS DMG installer
+- Port auto-detection with fallback — works even if port 3456 is already in use
 
 ## Requirements
 
@@ -47,13 +72,7 @@ During development (`npm run dev`), Vite starts a separate development server on
 
 ### macOS Menu Bar App
 
-Download the latest `TokenDash.dmg` from [GitHub Releases](https://github.com/zhangferry/tokendash/releases). Open the DMG and drag TokenDash to your Applications folder.
-
-The menu bar app shows real-time token usage in the status bar. Click the icon to open a compact popover dashboard with:
-- Today's token count and cost breakdown
-- Hourly consumption chart
-- Agent filter (show only Claude Code, Codex, etc.)
-- Settings: launch at login, check for updates, quit
+Download the latest `TokenDash-<version>-arm64.dmg` from [GitHub Releases](https://github.com/zhangferry/tokendash/releases). Open the DMG and drag TokenDash to your Applications folder. Launch it and the status bar icon appears immediately — no setup needed.
 
 ### Command Line Options
 
@@ -104,33 +123,6 @@ If you want to contribute or modify the dashboard locally:
 - **Testing:** Vitest (unit), Playwright (E2E). Run with `npm test` and `npm run test:e2e`.
 - **CI:** GitHub Actions pipeline for automated testing on every push and PR.
 
-## Changelog
-
-### v1.4.0
-- **macOS Menu Bar App** — native tray icon with real-time token count and cost in the status bar
-- **Popover Dashboard** — click the tray icon for a compact dashboard with hourly chart, agent filter, and settings
-- **Native Swift Tray Helper** — lightweight binary for macOS 26+ compatibility, drawn SVG icon
-- **Agent Filter** — choose which agents to display in both popover and tray badge, persisted across sessions
-- **Settings Panel** — launch at login, check for updates (via GitHub Releases), quit
-- **Update Checker** — automatic version check against GitHub Releases
-
-### v1.3.0
-- **Added OpenCode agent support** — parses SQLite database at `~/.local/share/opencode/opencode.db`
-- **Added Today by Hour panel** — 24-hour token consumption breakdown for the current day
-- **E2E test overhaul** — comprehensive Playwright test suite with fixture-based test data
-- **Added CI pipeline** — GitHub Actions for automated testing on push and PR
-- **Fixed model trend chart** — included `cacheReadTokens` in model trend calculations
-
-### v1.2.0
-- **Replaced `ccusage` CLI** with direct JSONL parser — data loads in 1-2ms instead of 12-30s
-- **Added code analytics** — code change trend, tool call trend, daily KPIs
-- **Added persistent disk cache** with stale-while-revalidate pattern
-- **Fixed heatmap** — cost metric now shows real data (was always $0)
-- **Fixed timezone handling** — correct date/hour grouping for non-UTC users
-- **Added pricing info popup** — shows per-model pricing formula in Cost mode
-- **Added test suite** — 49 unit tests + 6 E2E tests
-- **Layout improvements** — model trend bar chart, side-by-side analytics panels
-
 ## License
 
 [MIT](./LICENSE)