tokens-metric 0.4.13 → 0.4.14

package/README.md

@@ -1,19 +1,53 @@
 # tokens-metric
 
-Real-time token usage meter for [Claude Code](https://claude.com/claude-code) — a terminal UI plus a one-line statusline you can wire into Claude Code itself.
+Real-time token usage meter for [Claude Code](https://claude.com/claude-code) and [OpenAI Codex CLI](https://github.com/openai/codex) — a terminal UI plus a one-line statusline you can wire into Claude Code itself.
 
-It tails the transcripts Claude Code writes under `~/.claude/projects/**/*.jsonl`, aggregates the `usage` field of each message in-memory, and renders it live. No API calls, no telemetry.
+It tails the transcripts both tools write to disk, aggregates usage in-memory, and renders it live. No API calls, no telemetry.
+
+| Source | Transcript path |
+|--------|----------------|
+| Claude Code | `~/.claude/projects/**/*.jsonl` |
+| Codex CLI | `~/.codex/sessions/YYYY/MM/DD/*.jsonl` |
 
 ## What it shows
 
-### TUI (tab navigation)
+### Always-visible status bars
+
+One bar per active source, always on screen regardless of which panel is open:
+
+```
+● sonnet-4-6  ·  33.4M tok  ·  ~$23.21  ·  351 msgs  ·  since 17:23  ● live  2s ago
+● codex       ·  236M tok   ·  ~$165.35 ·  896 msgs  ·  since 18:19  ○ idle  3m ago
+```
+
+### [1] Breakdown
+
+- Input / output / cache-write / cache-read bars with percentages and per-category cost
+- Cache hit ratio with quality rating (excellent / degraded / poor)
+- Context window fill gauge for the last turn
+- Per-model totals when multiple models were used in a session
+- 32-second activity sparkline with peak and avg rate
+- **30-minute timeline chart** — vertical bar chart, one bucket per minute, stacked cyan (Claude) / magenta (Codex), oldest bars dimmed, current minute highlighted
+
+### [2] History
+
+Today / 7-day / 30-day aggregate: tokens, estimated cost, session count. Dual bar chart (Claude vs Codex) for the last 7 days. Data persisted in `~/.tokens-metric/history.json` so totals survive transcript rotation.
+
+### [3] Sessions
+
+Today's sessions sorted by start time. Navigate with `↑↓` — the selected session expands an inline detail panel showing per-category token bars, percentages, and cost breakdown.
+
+### [4] Transcripts
 
-- **Session status bar** — always visible: model, total tokens, estimated cost, message count, time since session start, mini activity sparkline, live/idle indicator.
-- **[1] Breakdown** — input / output / cache-write / cache-read token bars with percentages and per-category cost estimates, cache hit ratio, per-model totals, and a 32-second activity sparkline with peak/avg rate.
-- **[2] History** — today / 7-day / 30-day aggregate: tokens, estimated cost, session count, top model. Data is persisted locally in `~/.tokens-metric/history.json` so historical totals survive transcript rotation.
-- **[3] Sessions** — today's sessions sorted by start time: project path, model, tokens, cost, duration, active indicator.
-- **[4] Transcripts** — last five transcript files with recency timestamps.
-- **Update notifier** — checks npm once every 24 h (cached) and shows a banner when a newer version is available.
+Last five transcript files with recency timestamps.
+
+### Header
+
+```
+● Claude Code detected   ·   ● Codex detected   ·   4 sessions · 3 projects today
+```
+
+Codex detection dot is green when `~/.codex/` exists, red when not installed.
 
 ### Statusline
 
@@ -31,7 +65,7 @@ Or run without installing:
 npx tokens-metric
 ```
 
-Requires **Node 18+** and an existing Claude Code installation.
+Requires **Node 18+**. Claude Code and/or Codex CLI must be installed for data to appear.
 
 ## Usage
 
@@ -46,15 +80,16 @@ tokens-metric
 | `←` / `→` | Move cursor between tabs |
 | `Enter` | Open / collapse the focused tab |
 | `1` – `4` | Jump directly to a tab and open it |
+| `↑` / `↓` | Navigate sessions (while Sessions tab is open) |
 | `Esc` | Collapse the open panel |
 | `q` / `Ctrl-C` | Quit |
 
 ### Privacy defaults
 
-Starting in v0.2.0 the TUI masks identifying information by default so screenshots can be shared safely:
+Paths are masked by default so screenshots can be shared safely:
 
-- `cwd` paths are shown as `~/…` instead of `/Users/<you>/…`.
-- The user ID is masked to `●●●●●●●●`.
+- `cwd` paths shown as `~/…` instead of `/Users/<you>/…`
+- User IDs masked to `●●●●●●●●`
 
 Pass `--reveal` to show everything unmasked:
 
@@ -81,30 +116,41 @@ Output looks like:
 🏢 team opus-4-7 │ in 117 · out 43.5k · cache 3.21M │ Σ 3.25M · ~$12.29 API-eq
 ```
 
+## Pricing
+
+Costs are estimated at **API-equivalent pricing** — a reference figure, not what you pay on Pro/Max/Team subscriptions.
+
+| Provider | Models |
+|----------|--------|
+| Anthropic | claude-opus-4, claude-sonnet-4, claude-haiku-3.5, and prior generations |
+| OpenAI | o4-mini, o3, o3-mini, gpt-4o, gpt-4o-mini (via Codex CLI) |
+
+Prices are hardcoded in `src/core/format.ts`. Update the package when providers change their rates.
+
 ## Honest limitations
 
-1. **Plan tier is heuristic.** We read flags Claude Code writes locally (e.g. `opusProMigrationComplete`). Anthropic can rename these at any release; the detector falls back to `unknown` instead of breaking.
-2. **Pro vs. Max are not distinguishable locally.** Both look identical from the config file.
-3. **The USD figure is API-equivalent pricing, not what you actually pay.** On Pro/Max/Team you pay a flat subscription — the dollar number is purely a reference for what the same tokens would cost on the API.
-4. **Prices are hardcoded.** See `src/core/format.ts`. If Anthropic updates pricing, the numbers drift until you bump the package.
-5. **The transcript format is not a public API.** It works today; it may shift. The parser is intentionally tolerant of unexpected shapes.
+1. **Plan tier is heuristic.** We read flags Claude Code writes locally. Anthropic can rename these at any release; the detector falls back to `unknown`.
+2. **Pro vs. Max are not distinguishable locally.** Both look identical from config.
+3. **The transcript format is not a public API.** It works today; it may shift. The parser is intentionally tolerant of unexpected shapes.
+4. **Codex CLI model key is always `codex`.** The JSONL does not include a specific model name, so all Codex usage is priced at o4-mini rates.
 
 ## How it works
 
 ```
-~/.claude/projects/<encoded-cwd>/<session-id>.jsonl
-                 │
-                 ▼
-        src/core/parser.ts        reads + aggregates usage per message
-        src/core/tailer.ts        watches the active file with fs.watch
-        src/core/detect.ts        reads ~/.claude.json for auth + plan hints
-        src/core/history.ts       per-day aggregation with mtime-based cache
-        src/core/history-store.ts persists daily aggregates to ~/.tokens-metric/
-        src/core/updater.ts       npm version check, 24h cache
-                 │
-        ┌────────┴────────┐
-        ▼                 ▼
-  src/tui (Ink)     src/statusline
+~/.claude/projects/<encoded-cwd>/<session>.jsonl   ~/.codex/sessions/YYYY/MM/DD/<session>.jsonl
+                        │                                          │
+                        └──────────────┬───────────────────────────┘
+                                       ▼
+                          src/core/parser.ts      reads + aggregates usage per message
+                          src/core/tailer.ts      watches active files with fs.watch
+                          src/core/detect.ts      auth, plan hints, Codex detection
+                          src/core/history.ts     per-day aggregation, mtime cache
+                          src/core/history-store  persists daily totals to ~/.tokens-metric/
+                          src/core/updater.ts     npm version check, 24h cache
+                                       │
+                          ┌────────────┴────────────┐
+                          ▼                         ▼
+                    src/tui (Ink)            src/statusline
 ```
 
 ## Development
@@ -120,11 +166,7 @@ npm run build            # builds dist/
 
 ## Roadmap
 
-- **Windows support** — Claude Code on Windows stores transcripts in a different location (`%APPDATA%\Claude\`). This requires abstracting `claudeHome()` in `detect.ts` to resolve the correct path per OS, and handling Windows path separators in project folder names.
-
-- **Multi-provider support (Codex, Gemini, etc.)** — The pricing table in `format.ts` currently covers Claude models only. Adding other providers means extending the table with `gpt-*`, `gemini-*`, `o1-*` prefixes, investigating whether those agents produce compatible `.jsonl` transcripts, and likely allowing the user to point to additional transcript folders.
-
-- **Context window usage** — Show how much of the active session's context window is consumed. Claude Code may log this in the transcript; if not, it can be inferred per model (e.g. claude-3.5-sonnet = 200k tokens). Would appear as a progress bar in the session status bar or breakdown panel.
+- **Windows support** — Claude Code on Windows stores transcripts under `%APPDATA%\Claude\`. Requires abstracting `claudeHome()` in `detect.ts` and handling Windows path separators.
 
 ## License
 

package/dist/tui/index.js

@@ -357,10 +357,12 @@ function BarRow({ label, value, max, total, color, cost, }) {
     return (_jsxs(Text, { children: [_jsx(Text, { bold: true, children: label }), _jsx(Text, { color: color, children: bar(value / max, BAR_WIDTH) }), _jsxs(Text, { children: ["  ", fmtNumber(value).padStart(7, ' ')] }), _jsx(Text, { dimColor: true, children: `  ${pct.toFixed(1).padStart(5, ' ')}%` }), cost !== null && _jsx(Text, { dimColor: true, children: `  ~${fmtUSD(cost)}` })] }));
 }
 // ── 30-minute timeline chart ─────────────────────────────────────────────────
+const PARTIAL_BLOCKS = [' ', '▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
 function TimelineChart({ claudeTimeline, codexTimeline, }) {
     const combined = claudeTimeline.map((c, i) => c + (codexTimeline[i] ?? 0));
-    const max = Math.max(1, ...combined);
-    const hasData = combined.some((v) => v > 0);
+    const maxRaw = Math.max(...combined);
+    const hasData = maxRaw > 0;
+    const max = hasData ? maxRaw : 1;
     const N = claudeTimeline.length;
     const fmtY = (v) => {
         if (v >= 1_000_000)
@@ -369,7 +371,10 @@ function TimelineChart({ claudeTimeline, codexTimeline, }) {
             return `${Math.round(v / 1_000)}k`;
         return String(Math.round(v));
     };
+    // Y axis labels: only when there is real data
     const yLabel = (r) => {
+        if (!hasData)
+            return '     ';
         if (r === TIMELINE_ROWS - 1)
             return fmtY(max).padStart(5);
         if (r === Math.floor(TIMELINE_ROWS / 2))
@@ -377,15 +382,26 @@ function TimelineChart({ claudeTimeline, codexTimeline, }) {
         return '     ';
     };
     return (_jsxs(Box, { borderStyle: "round", borderColor: "yellow", paddingX: 1, flexDirection: "column", children: [_jsxs(Text, { bold: true, color: "yellow", children: ['activity ', _jsx(Text, { bold: false, dimColor: true, children: "\u00B7 last 30m" })] }), Array.from({ length: TIMELINE_ROWS }, (_, i) => {
-                const r = TIMELINE_ROWS - 1 - i;
-                const threshold = (r / TIMELINE_ROWS) * max;
+                const r = TIMELINE_ROWS - 1 - i; // r=ROWS-1 at top, r=0 at bottom
                 return (_jsxs(Text, { children: [_jsxs(Text, { dimColor: true, children: [yLabel(r), " \u2502"] }), combined.map((v, c) => {
-                            const filled = v > threshold;
-                            const isCodex = filled && (codexTimeline[c] ?? 0) > threshold;
-                            return (_jsx(Text, { color: filled ? (isCodex ? 'magenta' : 'cyan') : undefined, children: filled ? '█' : ' ' }, c));
+                            // fractional bar heights in row units
+                            const totalH = (v / max) * TIMELINE_ROWS;
+                            const codexH = ((codexTimeline[c] ?? 0) / max) * TIMELINE_ROWS;
+                            if (totalH <= r)
+                                return _jsx(Text, { children: " " }, c);
+                            // smooth top using partial block chars
+                            const char = totalH >= r + 1
+                                ? '█'
+                                : (PARTIAL_BLOCKS[Math.max(1, Math.round((totalH - r) * 8))] ?? '█');
+                            // stacked color: codex fills from bottom, claude on top
+                            const isCodex = codexH > r + 0.5;
+                            // oldest third dimmed, current minute (rightmost) bright
+                            const isCurrentMinute = c === N - 1;
+                            const isOld = c < Math.floor(N / 3);
+                            return (_jsx(Text, { color: isCodex ? 'magenta' : 'cyan', dimColor: isOld && !isCurrentMinute, bold: isCurrentMinute, children: char }, c));
                         })] }, r));
             }), _jsx(Text, { dimColor: true, children: '      └' + '─'.repeat(N) }), _jsx(Text, { dimColor: true, children: `      -30m${' '.repeat(Math.max(0, N - 7))}now` }), _jsx(Box, { marginTop: 1, children: hasData
-                    ? _jsxs(Text, { dimColor: true, children: ["peak ", _jsx(Text, { color: "white", children: fmtY(max) }), "/min  \u00B7  ", _jsx(Text, { color: "cyan", children: "\u2588" }), " claude  ", _jsx(Text, { color: "magenta", children: "\u2588" }), " codex"] })
+                    ? _jsxs(Text, { dimColor: true, children: ['peak ', _jsx(Text, { color: "white", children: fmtY(max) }), '/min  ·  ', _jsx(Text, { color: "cyan", children: '█' }), ' claude  ', _jsx(Text, { color: "magenta", children: '█' }), ' codex'] })
                     : _jsx(Text, { dimColor: true, children: "filling\u2026 (1 bar/min)" }) })] }));
 }
 // ── History panel ────────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokens-metric",
-  "version": "0.4.13",
+  "version": "0.4.14",
   "description": "Real-time token usage meter for Claude Code — statusline + Ink TUI.",
   "type": "module",
   "bin": {