ccgauge 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,122 @@
+# Changelog
+
+All notable changes to **ccgauge** are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] — 2026-05-05
+
+This release adds **OpenAI Codex CLI** as a first-class data source alongside
+Claude Code, ships a background-indexed data layer for instant page
+navigation, and overhauls the `/usage` page so it no longer ships megabytes
+of HTML to the browser.
+
+### Added
+
+- **Multi-provider support.** New `lib/providers/` adapter layer; toggle
+  between **Claude Code** and **OpenAI Codex CLI** from the nav bar.
+  Source persists via `?source=` URL param + cookie. Adding a third
+  provider is a single new file plus a one-line registry entry.
+- **Background indexer** (`lib/data-loader/indexer.ts`) — `fs.watch`-driven,
+  with a 30 s polling fallback and per-file `mtime+size` deduplication.
+  Pages now read an in-memory snapshot in O(1) instead of triggering a
+  scan on every navigation.
+- **Persisted index** at `~/.ccgauge/cache/index-vN.json`, with schema
+  versioning and per-entry `parserVersion` so semantic parser fixes
+  auto-invalidate stale records on the next startup. Restart goes from
+  ~750 ms full scan to ~110 ms cache restore.
+- **Server-side pagination** for `/usage`. URL-driven search / sort /
+  page; only the current page's 25 turns are sent to the client.
+  Real-data HTML payload drops from **~3.58 MB to ~40 KB** (89× smaller).
+- **Streaming CSV export** (`/api/export/usage`) with formula-injection
+  guard (escapes leading `=`, `+`, `-`, `@`).
+- **Source switcher** in the nav with brand-coloured active state, plus
+  `prefetch={false}` on tabs so opening the dashboard doesn't preload
+  every heavy page.
+- **`reasoning_tokens` breakdown** surfaced in token-total hover cards and
+  the session timeline, so OpenAI users can see how much of their output
+  was reasoning (typically the dominant cost driver).
+- **Indexer status panel** in **Settings**: last indexed at, index
+  duration, active watchers, loaded-from-disk flag, recent errors.
+- **Unified API error handler** (`lib/api/error-handler.ts`) — every
+  route returns structured JSON 500 with a sanitized message instead of
+  HTML stack pages. Indexer errors leaked through `/api/scan` are
+  scrubbed of `$HOME` paths.
+- **Codex parser smoke test** (`pnpm test`) covering token-count
+  semantics, parser version, reasoning-detail emission, and pricing.
+
+### Changed
+
+- **Brand colour** moved from Anthropic orange to Indigo so the
+  dashboard's chrome doesn't clash with the (warm) Claude / Codex
+  per-provider chips.
+- **Overview header counts** now reflect the **active source** instead
+  of mixing Claude + Codex global totals.
+- **Codex parser** rewritten to derive each emitted record's tokens
+  from the forward delta of `total_token_usage`, fixing a ~26 %
+  over-count caused by duplicate / refresh `token_count` events
+  (Codex now bills $134.63 instead of $165.63 for the same 70-file
+  dataset).
+- **Output token convention** for Codex: `output_tokens` includes
+  reasoning tokens (matches OpenAI Responses API billing); reasoning
+  is exposed separately as a display-only breakdown that does not
+  double-count.
+- **Codex parser timestamp fallback chain** (event → session_meta →
+  last valid → file mtime → now) so events without a timestamp don't
+  break sort or time bucketing.
+- **Internationalised settings** with Codex / Claude data source
+  display names, indexer status keys, and reasoning breakdown labels.
+
+### Fixed
+
+- **Nav bar shake on tab switch.** `html { overflow-y: scroll }` reserves
+  the scrollbar gutter so navigations between short and tall pages no
+  longer shift the centred nav horizontally.
+- **`forceRescan` race condition.** Concurrent `POST /api/scan` calls
+  are now coalesced onto a single in-flight Promise, so the in-memory
+  index Map can't be wiped mid-scan.
+- **Provider root not detected post-startup.** The poll loop re-detects
+  data directories every 30 s, so a Codex/Claude install that appears
+  after launch is picked up automatically.
+- **Search debounce leak** — `UsageTable` clears its pending `router.push`
+  timer on unmount so navigating away mid-typing doesn't yank you back
+  to `/usage`.
+- **`?page=NaN` / non-numeric inputs** were rendering an undefined page.
+  Strict `Number.isFinite` guard, falls back to page 1.
+- **`stats.durationMs` was misleading** after the indexer split work
+  across phases. It now reflects the wall-clock from work start to
+  snapshot ready.
+- **Fast Refresh resets** during dev: indexer instance is stored on
+  `globalThis` so HMR doesn't re-scan on every code save.
+
+### Security
+
+- **CSV formula injection guard** in `/api/export/usage`: cells starting
+  with `=`, `+`, `-`, `@`, `\t`, or `\r` are prefixed with `'` so
+  spreadsheet apps render them as text instead of executing as formulas.
+- **Path sanitisation** in indexer error history: absolute paths
+  containing the OS username are rewritten to `~` before being exposed
+  via `/api/scan` and the Settings UI.
+
+### Performance
+
+| Metric                         | Before         | After      |
+| ------------------------------ | -------------- | ---------- |
+| `/usage?codex&all` HTML        | 3.58 MB        | **40 KB**  |
+| `/usage?claude&7d` HTML        | 1.57 MB        | **34 KB**  |
+| TTFB (warm)                    | 36–57 ms       | **15–19 ms** |
+| Cold start with persisted cache | 747 ms (rescan) | **110 ms (restore)** |
+
+## [0.2.0] — 2026-04-30
+
+- One-click language + theme toggles refined in the header.
+- Internal site-wide UX cleanup ahead of multi-provider support.
+
+## [0.1.x]
+
+- Initial public release as `ccgauge`: local Next.js dashboard for
+  Claude Code token usage, cost, and 5-hour block tracking.
+
+[0.3.0]: https://github.com/chengzuopeng/ccgauge/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/chengzuopeng/ccgauge/compare/v0.1.1...v0.2.0

package/README.md

@@ -2,11 +2,11 @@
 
 # ccgauge
 
-Local web dashboard for your Claude Code token usage and cost. Zero-config.
+**Local, privacy-first usage dashboard for AI coding CLIs.** Track tokens, cost, and prompt-caching savings across **Claude Code** and **OpenAI Codex CLI** in a single browser tab — without sending a byte to anyone.
 
-[![npm version](https://img.shields.io/npm/v/ccgauge?color=C96442&style=flat-square)](https://www.npmjs.com/package/ccgauge)
-[![license](https://img.shields.io/npm/l/ccgauge?color=C96442&style=flat-square)](./LICENSE)
-[![node](https://img.shields.io/node/v/ccgauge?color=C96442&style=flat-square)](#)
+[![npm version](https://img.shields.io/npm/v/ccgauge?color=4F46E5&style=flat-square)](https://www.npmjs.com/package/ccgauge)
+[![license](https://img.shields.io/npm/l/ccgauge?color=4F46E5&style=flat-square)](./LICENSE)
+[![node](https://img.shields.io/node/v/ccgauge?color=4F46E5&style=flat-square)](#)
 
 [English](./README.md) · [简体中文](./README.zh-CN.md)
 
@@ -16,72 +16,188 @@ Local web dashboard for your Claude Code token usage and cost. Zero-config.
 npx ccgauge
 ```
 
-That's it. ccgauge scans `~/.claude/projects/` (and `~/.config/claude/projects/`), reads the JSONL files, computes token usage + USD cost + cache savings, and opens a dashboard in your browser. **Data never leaves your machine.**
+One command. ccgauge reads the JSONL session files Claude Code and Codex CLI already write to your disk, computes per-day / per-project / per-model token usage and **dollar-equivalent cost**, then opens a unified web dashboard in your browser. Switch between data sources with one click. **No login, no telemetry, no network calls.**
 
 ![Overview — English / Dark](./docs/screenshots/overview-en-dark.png)
 
 ---
 
-## Why
+## Why ccgauge
 
-[ccusage](https://github.com/ryoppippi/ccusage) (the de-facto standard) is a great terminal CLI but it's a wall of numbers. ccgauge gives you the same data with charts, drill-down by project / session / model, a live 5-hour-block countdown, and a clear **"saved by cache"** KPI — all in a polished local web UI. Bilingual (English + 中文), light + dark themes, completely offline.
+If you pay per token on the API, or sit on a Claude Pro / Max / Team / Codex Plus subscription, you've probably wondered:
 
-## Features
+- *"How much would Claude Code have cost me on the API this month?"*
+- *"Is prompt caching actually saving me money — and how much?"*
+- *"Which project / session / model is eating the most tokens?"*
+- *"How close am I to the 5-hour rate-limit window resetting?"*
 
-- **Overview** — KPI cards: tokens today, cost today, this month, cache hit rate, top model, sessions today
-- **Live 5h block** — countdown + progress + burn rate + projected total cost
-- **Token usage trend** — stacked bar chart broken down by `input` / `output` / `cache_read` / `cache_creation`
-- **Sessions** — per-conversation list with model / tokens / cost / duration; click into the message-level timeline
-- **Projects** — per-`cwd` aggregation cards with sparkline + spend share
-- **Models** — side-by-side comparison: cost share, tokens share, cache hit rate, USD pricing
-- **Cache savings** — separate KPI showing how much cache reads have saved you vs. paying full input price
-- **i18n** — English / 中文, persisted to localStorage + cookie (no flash on initial paint)
-- **Themes** — Light / Dark / System (no flash, follows `prefers-color-scheme` when set to System)
-- **Filters** — time range (today / 7d / 30d / 90d / all), granularity (hour / day / week / month), model multi-select, project multi-select
-- **Export** — CSV download of the request log
-- **100% local** — read-only access to JSONL files, no telemetry, no network calls
+The terminal-based [ccusage](https://github.com/ryoppippi/ccusage) is great for printing tables. ccgauge gives you **the same data plus charts, drill-down, a live 5-hour block countdown — and it's the unified dashboard for both Claude Code and OpenAI Codex CLI side by side**.
 
-## Install / Run
+Everything runs locally as a Next.js app. Your conversation transcripts never leave the machine.
+
+## Highlights
+
+### Cross-provider analytics
+- One dashboard for both **Claude Code** and **OpenAI Codex CLI**
+- Toggle data source from the nav bar; URL persists via `?source=`, last choice cached in cookie
+- Built-in **provider adapter layer** (`lib/providers/`) — adding a third CLI (Gemini CLI, Cursor, Aider, …) is one new file plus a single registry line
+
+### At-a-glance KPIs
+- **Tokens today**, cost today, this month, cache hit rate, top model, active sessions
+- Day-over-day delta on every card (`vs yesterday`)
+- **Live 5-hour block** — countdown, progress bar, burn-rate per minute, projected total cost
+
+### Drill-down everywhere
+- **Sessions** — per-conversation list with model / tokens / cost / duration, plus a message-level timeline
+- **Projects** — per-`cwd` aggregation cards with sparkline and spend share
+- **Models** — side-by-side comparison: cost share, tokens share, cache hit, USD pricing
+- **Usage** — turn-grouped table with expandable tool-call breakdown, CSV export
+
+### Cost transparency
+- **Cache savings** is its own KPI — quantifies how much Anthropic prompt caching saved you vs. paying full input price
+- Codex cost shown as the **OpenAI API equivalent** so subscription users can compare value against pay-as-you-go
+- Built-in pricing tables: 12 Claude models + the gpt-5 family + o-series; unknown models fall back to family-latest
+
+### Polished local UI
+- **Light / Dark / System** themes, no flash of incorrect theme
+- **English / 中文** (cookie + localStorage)
+- Filters: time range (today / 7d / 30d / 90d / all), granularity (hour / day / week / month), model and project multi-select
+
+### Privacy by design
+- 100 % local: read-only access to existing JSONL files, zero outbound network calls
+- Open source, MIT-licensed
+- Background mode for a quiet always-on service, with `start / stop / restart / status / open / logs` lifecycle commands
+
+## Quick start
+
+Zero-install one-shot:
 
 ```bash
-# zero-install one-shot (recommended)
 npx ccgauge
+```
+
+Or install globally:
+
+```bash
+npm  i -g ccgauge && ccgauge          # npm
+pnpm i -g ccgauge && ccgauge          # pnpm
+yarn global add ccgauge && ccgauge    # yarn
+```
+
+The dashboard opens at [http://localhost:3737](http://localhost:3737). If 3737 is taken, ccgauge falls back to the next free port automatically. Press `Ctrl+C` to stop.
+
+**Requirements:** Node.js 20+ (Node 22 recommended for `pnpm test`). Works on macOS, Linux, and Windows.
+
+## CLI reference
 
-# global install
-npm  i -g ccgauge     && ccgauge
-pnpm i -g ccgauge     && ccgauge
-yarn global add ccgauge && ccgauge
+`ccgauge` is shorthand for `ccgauge start`, so flags work after either command.
 
-# dlx
-pnpm dlx ccgauge
+### Foreground (default)
+
+```bash
+ccgauge
+ccgauge --port 4000 --no-open
+ccgauge start --host 0.0.0.0 --port 4000
 ```
 
-### Options
+### Background service
 
+```bash
+ccgauge start --background
+
+ccgauge status
+ccgauge open
+ccgauge logs           # last 80 lines
+ccgauge logs --follow  # tail in real time
+ccgauge restart --port 4000
+ccgauge stop
 ```
-ccgauge [options]
-
-  -p, --port <port>     preferred port (default: 3737)
-  -h, --host <host>     bind host (default: 127.0.0.1)
-      --no-open         do not auto-open the browser
-      --dir <path>      override Claude config dir (will append /projects)
-  -q, --quiet           silence Next.js output
-  -V, --version         output version
-      --help            show help
+
+Background mode persists state under `~/.ccgauge/`:
+- `state.json` — PID, URL, start time, log file path
+- `ccgauge.log` — server output (read by `ccgauge logs`)
+- Override with `CCGAUGE_STATE_DIR=/path/to/dir` for isolated profiles or tests
+
+### Commands
+
+| Command | Purpose |
+| --- | --- |
+| `ccgauge`, `ccgauge start` | Start in foreground. `Ctrl+C` to stop. |
+| `ccgauge start --background` | Start a detached background service. |
+| `ccgauge stop [--force]` | Stop the background service. |
+| `ccgauge restart [options]` | Stop and re-start with new options. |
+| `ccgauge status [--json]` | Inspect the background service. |
+| `ccgauge open` | Open the running dashboard in your browser. |
+| `ccgauge logs [-f] [-n <lines>]` | Print background logs. |
+
+### Startup options
+
+| Option | Applies to | Purpose |
+| --- | --- | --- |
+| `-p, --port <port>` | start, restart, root | Preferred port. Default: `3737`. |
+| `-H, --host <host>` | start, restart, root | Bind host. Default: `127.0.0.1`. |
+| `--no-open` | start, root | Skip auto-open in foreground mode. (Background mode never auto-opens; use `ccgauge open` instead.) |
+| `--dir <path>` | start, restart, root | Add `<path>/projects` as a Claude data source. |
+| `-q, --quiet` | start, restart, root | Silence Next.js output. |
+| `-b, --background` | start, root | Run as a detached background service. |
+| `--strict-port` | start, restart, root | Fail if the preferred port is busy. |
+| `--log <path>` | start --background, restart | Background log file path. |
+
+## Configuration
+
+ccgauge auto-detects the standard locations:
+
+| Provider | Default sources |
+| --- | --- |
+| Claude Code | `~/.claude/projects`, `~/.config/claude/projects` |
+| OpenAI Codex CLI | `~/.codex/sessions`, `~/.codex/archived_sessions` |
+
+Override or extend via environment variables:
+
+| Variable | Effect |
+| --- | --- |
+| `CCGAUGE_CONFIG_DIR` | Add `<dir>/projects` as a Claude data source |
+| `CLAUDE_CONFIG_DIR` | Same as above (Claude Code 1.0.30+ compatible) |
+| `CCGAUGE_CODEX_DIR` | Add an extra Codex sessions directory |
+| `CODEX_HOME` | Add `<dir>/sessions` and `<dir>/archived_sessions` |
+| `CCGAUGE_STATE_DIR` | Override background service state/log directory |
+
+## Architecture
+
 ```
+~/.claude/projects/**/*.jsonl  ──┐
+                                 ├─►  ProviderAdapter registry
+~/.codex/sessions/**/*.jsonl  ───┘    │
+                                      ▼
+                              scanAll() ─► dedup ─► aggregate by
+                                                    time / model / project / session / 5h block
+                                                ▼
+                                  Next.js RSC pages + client charts
+```
+
+1. **CLI** (`bin/cli.mjs`) normalizes flags, validates the standalone build, picks a port via [`get-port`](https://github.com/sindresorhus/get-port).
+2. **Foreground** uses `fork()` and binds to your terminal; **background** uses detached `spawn()` with state in `~/.ccgauge/`.
+3. **Provider adapters** (`lib/providers/<name>/index.ts`) own data dirs, JSONL parser, pricing table, and model-name formatter. The registry-driven design means adding a third provider is one file plus one registry line.
+4. **Claude parser** reads each line as a typed event, extracts `usage` from assistant messages.
+5. **Codex parser** uses a turn state machine, emits one record per `event_msg.token_count` from `last_token_usage` (avoids cumulative double-counting), folds `cached_input_tokens` into cache-read and `reasoning_output_tokens` into output.
+6. **Pricing** ships built-in snapshots — Anthropic published rates for Claude (12 models) and OpenAI public rates for Codex (gpt-5 family + o-series). Codex cost is labelled "API equivalent" because subscription plans (Plus, Pro) bill differently.
+7. **i18n + theme** is cookie-driven SSR with a no-flash inline script in `<head>` and `localStorage` mirror.
 
-If `3737` is taken ccgauge falls back to the next available port automatically.
+## Adding a provider
 
-### Environment variables
+```
+lib/providers/<name>/
+  index.ts             ProviderAdapter implementation
+  parse-<name>.ts      JSONL → AssistantRecord[]
+  pricing.ts           model → Pricing
+  shorten-model.ts     pretty model names
+```
 
-| Variable              | Effect                                                              |
-| --------------------- | ------------------------------------------------------------------- |
-| `CCGAUGE_CONFIG_DIR`  | Use `<dir>/projects` as a data source (in addition to defaults)     |
-| `CLAUDE_CONFIG_DIR`   | Same as above (compatible with Claude Code 1.0.30+)                 |
+Register one line in `lib/providers/index.ts`, add the id to the `ProviderId` union, and you're done. `scan.ts`, the aggregator, the pricing module, and every page need no changes.
 
 ## Develop
 
-This repo is also a working Next.js project — you can run the dashboard against your live data while iterating on the code.
+This repo is a working Next.js project — run the dashboard against your live data while iterating.
 
 ```bash
 git clone https://github.com/chengzuopeng/ccgauge.git
@@ -90,46 +206,66 @@ pnpm install
 pnpm dev               # http://localhost:3737
 ```
 
-Other handy scripts:
+Scripts:
 
 ```bash
 pnpm typecheck         # tsc --noEmit
-pnpm lint              # next lint
+pnpm lint              # eslint .
+pnpm test              # codex parser smoke test (Node 22+)
 pnpm build             # next build + copy static into .next/standalone
 pnpm start             # run bin/cli.mjs against the standalone build
-pnpm screenshots       # regenerate docs/screenshots/*.png (requires Chromium)
-pnpm clean             # rm -rf .next node_modules tsconfig.tsbuildinfo
+pnpm screenshots       # regenerate docs/screenshots/*.png
+pnpm clean             # rm -rf .next node_modules
 ```
 
-To produce the npm-publishable artifact:
+Publish:
 
 ```bash
-pnpm build
-node bin/cli.mjs       # exact same entrypoint as `npx ccgauge`
+pnpm pack              # preview the tarball
+pnpm publish --access public  # runs `pnpm build` first via prepublishOnly
 ```
 
-To preview what would be published:
+## Troubleshooting
 
-```bash
-pnpm pack              # writes ccgauge-<version>.tgz; tar -tzf to inspect
-```
+| Symptom | Try |
+| --- | --- |
+| Port keeps drifting | `ccgauge --strict-port --port 3737` |
+| Stale background service | `ccgauge status`, then `ccgauge stop --force` |
+| Background didn't start | `ccgauge logs` reads `~/.ccgauge/ccgauge.log` |
+| Need an isolated profile | `CCGAUGE_STATE_DIR=/tmp/ccgauge-test ccgauge start -b` |
+| No data shown for Codex | Ensure `~/.codex/sessions` exists; check the **Settings** page for detected paths |
+| Want to bypass auto-open | `ccgauge --no-open` |
 
-## Publish
+## FAQ
 
-```bash
-# bump version in package.json, then:
-pnpm publish --access public
-```
+**Does ccgauge upload my conversations or transcripts?**
+No. ccgauge runs entirely on your machine. It only reads the JSONL files Claude Code and Codex CLI already store locally. There are zero outbound network calls.
+
+**How is this different from ccusage?**
+[ccusage](https://github.com/ryoppippi/ccusage) is a terminal CLI that prints usage tables. ccgauge is a polished web dashboard with charts, per-session drill-down, a 5-hour rate-limit countdown, project / model breakdowns, and **also covers OpenAI Codex CLI** out of the box.
+
+**Does it work for Claude Pro / Max / Team / Codex Plus subscribers?**
+Yes. The dashboard always reports the **API-equivalent dollar value** of your usage so you can see "how much would this have cost on PAYG". Subscription plans bill differently; ccgauge is not your invoice.
+
+**Which models / providers are supported?**
+- **Claude Code**: all `claude-*` models (Opus / Sonnet / Haiku, 3.x and 4.x)
+- **OpenAI Codex CLI**: gpt-5 family (gpt-5, gpt-5-mini, gpt-5-nano, gpt-5.4, gpt-5.5, gpt-5.5-mini, gpt-5.5-nano), gpt-4.1 / gpt-4.1-mini, plus o-series (o3, o4-mini)
+- Unknown models fall back to family-latest pricing automatically
+
+**Can I add my own provider?**
+Yes — see [Adding a provider](#adding-a-provider). The provider adapter layer is the explicit extension point.
 
-`prepublishOnly` runs `pnpm build` first, so the `.next/standalone` artifact is always fresh.
+**Does it require Anthropic or OpenAI credentials?**
+No. ccgauge never calls upstream APIs. It reads the local JSONL transcripts those CLIs already write.
 
-## How it works
+## Keywords
 
-1. **CLI** (`bin/cli.mjs`) picks an available port via [`get-port`](https://github.com/sindresorhus/get-port), then `fork()`s the Next.js standalone server (`.next/standalone/server.js`).
-2. Once the server responds, it [`open()`](https://github.com/sindresorhus/open)s the browser to that URL.
-3. The Next.js server-side code in `lib/data-loader/scan.ts` reads `~/.claude/projects/**/*.jsonl`, parses every `assistant` message, dedups via `(message.id, requestId)`, and aggregates by day / model / project / session / 5h-block.
-4. Pricing is from a built-in snapshot of Anthropic's published rates (12 models). Unknown models fall back to the same family's latest rate.
-5. i18n + theme: cookie-driven SSR + `localStorage` mirror + an inline no-flash script in `<head>`.
+`claude code dashboard` · `claude code usage` · `claude code cost tracker` · `claude code analytics` ·
+`codex cli usage` · `codex cli dashboard` · `openai codex usage` · `openai codex tracker` ·
+`ai cli token tracker` · `ai coding assistant cost` · `claude pro plan usage monitor` ·
+`claude max plan tracker` · `codex plus plan usage` · `prompt caching savings dashboard` ·
+`5-hour block tracker` · `rate limit window monitor` · `ccusage alternative` · `ccusage web ui` ·
+`token usage analytics` · `agentic coding stats` · `local ai usage monitor` · `self-hosted ai dashboard`
 
 ## License