tokens-metric 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Annibal48
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# 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.
+
+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.
+
+## What it shows
+
+- **Active session**: model, message count, time since last event, total tokens, equivalent API cost, tokens-per-minute rate, and an activity sparkline.
+- **Breakdown**: input / output / cache-write / cache-read tokens with proportional bars, plus per-model totals.
+- **Plan detection** (best-effort, local-only): API key vs. OAuth subscription, and a hint between Free, Pro/Max, or Team/Enterprise, inferred from flags in `~/.claude.json`.
+- **Recent transcripts**: last five sessions across all your projects.
+
+## Install
+
+```bash
+npm install -g tokens-metric
+```
+
+Or run without installing:
+
+```bash
+npx tokens-metric
+```
+
+Requires Node 18+ and an existing Claude Code installation.
+
+## Usage
+
+### TUI
+
+```bash
+tokens-metric
+```
+
+Press `q` (or `Esc`, or `Ctrl-C`) to quit.
+
+### Statusline inside Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "tokens-metric-statusline"
+  }
+}
+```
+
+Output looks like:
+
+```
+🏢 team opus-4-7 │ in 117 · out 43.5k · cache 3.21M │ Σ 3.25M · ~$12.29 API-eq
+```
+
+## Honest limitations
+
+1. **Plan tier is heuristic.** We read flags Claude Code writes locally (e.g. `opusProMigrationComplete`, `cachedExtraUsageDisabledReason`). Anthropic can rename these at any release; if they change, 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.
+
+## 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/tui (Ink)     src/statusline
+```
+
+## Development
+
+```bash
+git clone https://github.com/Annibal48/Tokens-Metric.git
+cd Tokens-Metric
+npm install
+npm run dev:tui          # hot-runs the TUI from sources
+npm run dev:statusline   # prints one line
+npm run build            # builds dist/
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/core/detect.js

@@ -0,0 +1,129 @@
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export function claudeHome() {
+    return join(homedir(), '.claude');
+}
+export function claudeConfigPath() {
+    return join(homedir(), '.claude.json');
+}
+/**
+ * Detect whether Claude Code is installed, the user is logged in, and best-
+ * effort what plan they're on. All signals are LOCAL and BEST-EFFORT — we
+ * never claim authority over a plan tier Anthropic hasn't told us about.
+ */
+export function detectAuth() {
+    const binPath = whichClaude();
+    const installed = Boolean(binPath) || existsSync(claudeHome()) || existsSync(claudeConfigPath());
+    // 1. API key takes precedence over OAuth (Claude Code itself prefers it).
+    if (process.env.ANTHROPIC_API_KEY) {
+        return {
+            installed,
+            binPath,
+            loggedIn: true,
+            authMethod: 'api-key',
+            planHint: 'api',
+            hint: 'ANTHROPIC_API_KEY is set — pay-per-token API billing.',
+        };
+    }
+    // 2. OAuth / subscription: ~/.claude.json holds a `userID` once logged in.
+    //    The actual access token lives elsewhere (Keychain on macOS), but we
+    //    don't need it — userID is sufficient proof of login.
+    const cfg = readClaudeConfig();
+    const userId = typeof cfg?.userID === 'string' ? cfg.userID : '';
+    if (userId) {
+        const planHint = inferPlanHint(cfg);
+        return {
+            installed,
+            binPath,
+            loggedIn: true,
+            authMethod: 'oauth-subscription',
+            planHint,
+            userIdShort: userId.slice(0, 8),
+            hint: planHintExplanation(planHint, cfg),
+        };
+    }
+    // 3. Installed but not logged in.
+    if (installed) {
+        return {
+            installed,
+            binPath,
+            loggedIn: false,
+            authMethod: 'none',
+            planHint: 'unknown',
+            hint: 'Claude Code is installed but no userID was found in ~/.claude.json. Run `claude` to log in.',
+        };
+    }
+    return {
+        installed: false,
+        loggedIn: false,
+        authMethod: 'none',
+        planHint: 'unknown',
+        hint: 'Claude Code does not appear to be installed.',
+    };
+}
+function whichClaude() {
+    try {
+        return execSync('command -v claude', { stdio: ['ignore', 'pipe', 'ignore'] })
+            .toString()
+            .trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readClaudeConfig() {
+    const p = claudeConfigPath();
+    if (!existsSync(p))
+        return null;
+    try {
+        // The file is ~22KB and JSON — parse it once.
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Heuristic plan inference. These signals come from `~/.claude.json` flags
+ * that Claude Code itself writes after migrations/feature gates run. They
+ * are correlational, not authoritative — Anthropic could change them at any
+ * release.
+ *
+ * - `opusProMigrationComplete: true` is set for accounts that have been
+ *   migrated to the Opus-on-Pro rollout — strong signal of a paid plan
+ *   (Pro / Max / Team / Enterprise).
+ * - `cachedExtraUsageDisabledReason: "org_level_disabled"` is set on
+ *   Team/Enterprise accounts whose org admin has disabled extra usage. It's
+ *   a strong hint of an org-managed seat.
+ */
+function inferPlanHint(cfg) {
+    if (!cfg)
+        return 'unknown';
+    if (cfg.cachedExtraUsageDisabledReason === 'org_level_disabled') {
+        return 'team-or-enterprise';
+    }
+    if (cfg.opusProMigrationComplete === true)
+        return 'paid';
+    // Logged in but no Opus-Pro migration flag → most likely Free, but not
+    // guaranteed (could be a fresh paid account before migration).
+    return 'free';
+}
+function planHintExplanation(plan, cfg) {
+    switch (plan) {
+        case 'team-or-enterprise':
+            return 'Org-managed seat detected (cachedExtraUsageDisabledReason=org_level_disabled). Likely Team or Enterprise.';
+        case 'paid':
+            return 'Paid plan likely (Opus-on-Pro migration flag is set). Pro/Max not distinguishable locally.';
+        case 'free':
+            return cfg
+                ? 'Logged in, but no paid-plan migration flag found. Likely Free (or very recently upgraded).'
+                : 'Logged in.';
+        case 'api':
+            return 'API key billing.';
+        case 'unknown':
+        default:
+            return 'Plan tier not determinable from local signals.';
+    }
+}

package/dist/core/format.js

@@ -0,0 +1,48 @@
+export function fmtNumber(n) {
+    if (n < 1000)
+        return `${n}`;
+    if (n < 1_000_000)
+        return `${(n / 1000).toFixed(1)}k`;
+    return `${(n / 1_000_000).toFixed(2)}M`;
+}
+/**
+ * Reference-only USD cost using public Anthropic API pricing. NOT a real bill
+ * when the user is on a Pro/Max subscription. Numbers here are conservative
+ * defaults — keep them updateable.
+ */
+const PRICES_PER_MTOK = {
+    // Claude Sonnet 4.x family
+    'claude-sonnet-4': { in: 3, out: 15, cacheWrite: 3.75, cacheRead: 0.3 },
+    // Opus 4.x family
+    'claude-opus-4': { in: 15, out: 75, cacheWrite: 18.75, cacheRead: 1.5 },
+    // Haiku 4.x family
+    'claude-haiku-4': { in: 0.8, out: 4, cacheWrite: 1, cacheRead: 0.08 },
+};
+function priceKey(model) {
+    const m = model.toLowerCase();
+    if (m.includes('opus'))
+        return 'claude-opus-4';
+    if (m.includes('haiku'))
+        return 'claude-haiku-4';
+    if (m.includes('sonnet'))
+        return 'claude-sonnet-4';
+    return null;
+}
+export function estimateCostUSD(model, u) {
+    const key = priceKey(model);
+    if (!key)
+        return null;
+    const p = PRICES_PER_MTOK[key];
+    const perTok = 1 / 1_000_000;
+    return (u.input_tokens * p.in * perTok +
+        u.output_tokens * p.out * perTok +
+        u.cache_creation_input_tokens * p.cacheWrite * perTok +
+        u.cache_read_input_tokens * p.cacheRead * perTok);
+}
+export function fmtUSD(n) {
+    if (n < 0.01)
+        return `$${n.toFixed(4)}`;
+    if (n < 1)
+        return `$${n.toFixed(3)}`;
+    return `$${n.toFixed(2)}`;
+}

package/dist/core/parser.js

@@ -0,0 +1,141 @@
+import { readdirSync, statSync, createReadStream, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { claudeHome } from './detect.js';
+import { addUsage, EMPTY_USAGE, } from './types.js';
+const PROJECTS_DIR = () => join(claudeHome(), 'projects');
+/**
+ * Walk ~/.claude/projects/<encoded-cwd>/*.jsonl and return all transcript
+ * files sorted by mtime descending (most recent first).
+ */
+export function listTranscripts() {
+    const root = PROJECTS_DIR();
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    for (const projectDir of safeReaddir(root)) {
+        const full = join(root, projectDir);
+        let stat;
+        try {
+            stat = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isDirectory())
+            continue;
+        for (const f of safeReaddir(full)) {
+            if (!f.endsWith('.jsonl'))
+                continue;
+            const p = join(full, f);
+            try {
+                const s = statSync(p);
+                out.push({ path: p, mtimeMs: s.mtimeMs, cwd: decodeCwd(projectDir) });
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    return out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+function safeReaddir(p) {
+    try {
+        return readdirSync(p);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Claude Code encodes the cwd by replacing path separators with `-`.
+ * We can't perfectly recover the original, but we can give a best-effort
+ * human-readable hint.
+ */
+function decodeCwd(encoded) {
+    return encoded.replace(/^-/, '/').replace(/-/g, '/');
+}
+/**
+ * Pick the most recently active transcript within `withinMs` (default 5 min).
+ */
+export function findActiveTranscript(withinMs = 5 * 60_000) {
+    const list = listTranscripts();
+    if (list.length === 0)
+        return null;
+    const top = list[0];
+    if (Date.now() - top.mtimeMs > withinMs) {
+        // Still return it as "last known", but caller can decide.
+        return { path: top.path, cwd: top.cwd };
+    }
+    return { path: top.path, cwd: top.cwd };
+}
+/**
+ * Read a JSONL transcript fully and aggregate usage stats.
+ */
+export async function aggregateTranscript(path) {
+    const stats = {
+        sessionId: deriveSessionId(path),
+        transcriptPath: path,
+        totals: EMPTY_USAGE(),
+        byModel: {},
+        messageCount: 0,
+    };
+    const stream = createReadStream(path, { encoding: 'utf8' });
+    const rl = createInterface({ input: stream, crlfDelay: Infinity });
+    for await (const line of rl) {
+        if (!line.trim())
+            continue;
+        applyLine(stats, line);
+    }
+    return stats;
+}
+export function deriveSessionId(path) {
+    const base = path.split('/').pop() ?? path;
+    return base.replace(/\.jsonl$/, '');
+}
+/**
+ * Apply a single JSONL line to a running stats object. Tolerant to
+ * unexpected shapes — Claude Code's transcript format evolves.
+ */
+export function applyLine(stats, line) {
+    let evt;
+    try {
+        evt = JSON.parse(line);
+    }
+    catch {
+        return;
+    }
+    if (typeof evt?.cwd === 'string' && !stats.cwd)
+        stats.cwd = evt.cwd;
+    const ts = parseTimestamp(evt?.timestamp);
+    if (ts) {
+        stats.startedAt = stats.startedAt ? Math.min(stats.startedAt, ts) : ts;
+        stats.lastEventAt = stats.lastEventAt ? Math.max(stats.lastEventAt, ts) : ts;
+    }
+    const message = evt?.message;
+    if (!message || typeof message !== 'object')
+        return;
+    const usage = message.usage;
+    if (!usage)
+        return;
+    const u = {
+        input_tokens: numberOr0(usage.input_tokens),
+        output_tokens: numberOr0(usage.output_tokens),
+        cache_creation_input_tokens: numberOr0(usage.cache_creation_input_tokens),
+        cache_read_input_tokens: numberOr0(usage.cache_read_input_tokens),
+    };
+    const model = typeof message.model === 'string' ? message.model : 'unknown';
+    stats.lastModel = model;
+    stats.totals = addUsage(stats.totals, u);
+    stats.byModel[model] = addUsage(stats.byModel[model] ?? EMPTY_USAGE(), u);
+    stats.messageCount += 1;
+}
+function numberOr0(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+}
+function parseTimestamp(v) {
+    if (typeof v !== 'string')
+        return undefined;
+    const n = Date.parse(v);
+    return Number.isFinite(n) ? n : undefined;
+}

package/dist/core/tailer.js

@@ -0,0 +1,82 @@
+import { open, watch } from 'node:fs/promises';
+import { statSync } from 'node:fs';
+import { applyLine } from './parser.js';
+import { EMPTY_USAGE } from './types.js';
+import { deriveSessionId } from './parser.js';
+/**
+ * Open a JSONL transcript, read everything currently in it, then watch for
+ * appended lines. Calls onUpdate whenever the stats change.
+ */
+export async function tailTranscript(path) {
+    const stats = {
+        sessionId: deriveSessionId(path),
+        transcriptPath: path,
+        totals: EMPTY_USAGE(),
+        byModel: {},
+        messageCount: 0,
+    };
+    const listeners = [];
+    const notify = () => listeners.forEach((l) => l(stats));
+    let fh = await open(path, 'r');
+    let offset = 0;
+    let buf = '';
+    let stopped = false;
+    async function drain() {
+        const size = statSync(path).size;
+        if (size < offset) {
+            // File was truncated/rotated — reopen.
+            await fh.close();
+            fh = await open(path, 'r');
+            offset = 0;
+            buf = '';
+        }
+        if (size === offset)
+            return;
+        const length = size - offset;
+        const chunk = Buffer.alloc(length);
+        const { bytesRead } = await fh.read(chunk, 0, length, offset);
+        offset += bytesRead;
+        buf += chunk.subarray(0, bytesRead).toString('utf8');
+        let nl;
+        let changed = false;
+        while ((nl = buf.indexOf('\n')) !== -1) {
+            const line = buf.slice(0, nl);
+            buf = buf.slice(nl + 1);
+            if (line.trim()) {
+                applyLine(stats, line);
+                changed = true;
+            }
+        }
+        if (changed)
+            notify();
+    }
+    await drain();
+    notify();
+    // Native watcher. fs.watch on macOS uses FSEvents and may coalesce; that's
+    // fine for our use case — we re-stat on each tick.
+    const ac = new AbortController();
+    (async () => {
+        try {
+            const watcher = watch(path, { signal: ac.signal });
+            for await (const _ of watcher) {
+                if (stopped)
+                    break;
+                await drain().catch(() => undefined);
+            }
+        }
+        catch {
+            // aborted or file gone
+        }
+    })();
+    return {
+        stats,
+        onUpdate(cb) {
+            listeners.push(cb);
+        },
+        async stop() {
+            stopped = true;
+            ac.abort();
+            await fh.close().catch(() => undefined);
+        },
+    };
+}

package/dist/core/types.js

@@ -0,0 +1,20 @@
+export const EMPTY_USAGE = () => ({
+    input_tokens: 0,
+    output_tokens: 0,
+    cache_creation_input_tokens: 0,
+    cache_read_input_tokens: 0,
+});
+export function addUsage(a, b) {
+    return {
+        input_tokens: a.input_tokens + (b.input_tokens ?? 0),
+        output_tokens: a.output_tokens + (b.output_tokens ?? 0),
+        cache_creation_input_tokens: a.cache_creation_input_tokens + (b.cache_creation_input_tokens ?? 0),
+        cache_read_input_tokens: a.cache_read_input_tokens + (b.cache_read_input_tokens ?? 0),
+    };
+}
+export function totalTokens(u) {
+    return (u.input_tokens +
+        u.output_tokens +
+        u.cache_creation_input_tokens +
+        u.cache_read_input_tokens);
+}

package/dist/statusline/index.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { aggregateTranscript, findActiveTranscript } from '../core/parser.js';
+import { detectAuth } from '../core/detect.js';
+import { estimateCostUSD, fmtNumber, fmtUSD } from '../core/format.js';
+import { totalTokens } from '../core/types.js';
+/**
+ * One-shot status line. Reads whatever JSONL is currently the most recent
+ * transcript, aggregates it, and prints a single line. Exits 0 always so
+ * Claude Code's statusLine doesn't blank out on errors.
+ */
+async function main() {
+    try {
+        const active = findActiveTranscript();
+        const auth = detectAuth();
+        if (!active) {
+            process.stdout.write(authBadge(auth) + ' · no active session');
+            return;
+        }
+        const s = await aggregateTranscript(active.path);
+        const model = s.lastModel ?? 'unknown';
+        const tot = totalTokens(s.totals);
+        const cost = estimateCostUSD(model, s.totals);
+        const costStr = cost !== null ? ` · ~${fmtUSD(cost)} API-eq` : '';
+        const line = `${authBadge(auth)} ` +
+            `${shortModel(model)} │ ` +
+            `in ${fmtNumber(s.totals.input_tokens)} · ` +
+            `out ${fmtNumber(s.totals.output_tokens)} · ` +
+            `cache ${fmtNumber(s.totals.cache_read_input_tokens + s.totals.cache_creation_input_tokens)} ` +
+            `│ Σ ${fmtNumber(tot)}` +
+            costStr;
+        process.stdout.write(line);
+    }
+    catch (err) {
+        process.stdout.write('tokens-metric · err');
+    }
+}
+function shortModel(m) {
+    return m
+        .replace(/^claude-/, '')
+        .replace(/-20\d{6}/, '')
+        .replace(/-\d{8}$/, '');
+}
+function authBadge(a) {
+    if (!a.installed)
+        return '⚠ no-cc';
+    if (!a.loggedIn)
+        return '🔒 logged-out';
+    switch (a.planHint) {
+        case 'api':
+            return '🔑 api';
+        case 'team-or-enterprise':
+            return '🏢 team';
+        case 'paid':
+            return '💎 paid';
+        case 'free':
+            return '🆓 free';
+        default:
+            return '🧠 sub';
+    }
+}
+main();

package/dist/tui/bars.js

@@ -0,0 +1,41 @@
+/**
+ * Tiny visual helpers — no dependencies, just unicode block characters.
+ */
+const BAR_BLOCKS = ['', '▏', '▎', '▍', '▌', '▋', '▊', '▉', '█'];
+/**
+ * Render a horizontal bar of `width` cells filled to `ratio` (0..1) using
+ * partial-block characters for sub-cell precision.
+ */
+export function bar(ratio, width) {
+    if (!Number.isFinite(ratio) || ratio < 0)
+        ratio = 0;
+    if (ratio > 1)
+        ratio = 1;
+    const total = ratio * width;
+    const full = Math.floor(total);
+    const remainder = total - full;
+    const partialIdx = Math.round(remainder * 8);
+    const partial = partialIdx > 0 ? BAR_BLOCKS[partialIdx] : '';
+    const empty = Math.max(0, width - full - (partial ? 1 : 0));
+    return '█'.repeat(full) + partial + ' '.repeat(empty);
+}
+const SPARK = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
+/**
+ * Map a numeric series into a fixed-width sparkline. Auto-scales to the
+ * series max. Returns empty cells when there's no data yet.
+ */
+export function sparkline(values, width) {
+    if (width <= 0)
+        return '';
+    const tail = values.slice(-width);
+    const padded = tail.length < width ? Array(width - tail.length).fill(0).concat(tail) : tail;
+    const max = Math.max(1, ...padded);
+    return padded
+        .map((v) => {
+        if (v <= 0)
+            return ' ';
+        const idx = Math.min(SPARK.length - 1, Math.floor((v / max) * (SPARK.length - 1)));
+        return SPARK[idx];
+    })
+        .join('');
+}

package/dist/tui/index.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { render, Box, Text, useApp, useInput } from 'ink';
+import { findActiveTranscript, listTranscripts } from '../core/parser.js';
+import { tailTranscript } from '../core/tailer.js';
+import { detectAuth } from '../core/detect.js';
+import { estimateCostUSD, fmtNumber, fmtUSD } from '../core/format.js';
+import { totalTokens } from '../core/types.js';
+import { bar, sparkline } from './bars.js';
+const RESCAN_MS = 3_000;
+const SPARK_WIDTH = 32;
+const BAR_WIDTH = 20;
+function App() {
+    const { exit } = useApp();
+    const [auth] = useState(() => detectAuth());
+    const [stats, setStats] = useState(null);
+    const [transcriptPath, setTranscriptPath] = useState(null);
+    const [rate, setRate] = useState(0);
+    const [series, setSeries] = useState(() => Array(SPARK_WIDTH).fill(0));
+    const [now, setNow] = useState(Date.now());
+    const lastTotalRef = useRef(0);
+    const lastSampleAtRef = useRef(Date.now());
+    // useInput requires raw mode (interactive TTY). Skip it when stdin is piped
+    // or otherwise non-interactive, so `node dist/tui/index.js | cat` still
+    // renders instead of crashing.
+    const interactive = Boolean(process.stdin.isTTY);
+    if (interactive) {
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        useInput((input, key) => {
+            if (input === 'q' || key.escape || (key.ctrl && input === 'c'))
+                exit();
+        });
+    }
+    // Wall-clock tick + sparkline slot rotation (1 Hz).
+    useEffect(() => {
+        const t = setInterval(() => {
+            setNow(Date.now());
+            setSeries((s) => [...s.slice(1), 0]);
+        }, 1000);
+        return () => clearInterval(t);
+    }, []);
+    useEffect(() => {
+        let handle = null;
+        let cancelled = false;
+        async function attach(path) {
+            handle?.stop().catch(() => undefined);
+            setTranscriptPath(path);
+            handle = await tailTranscript(path);
+            if (cancelled) {
+                handle.stop();
+                return;
+            }
+            handle.onUpdate((s) => {
+                const tot = totalTokens(s.totals);
+                const delta = Math.max(0, tot - lastTotalRef.current);
+                const dt = (Date.now() - lastSampleAtRef.current) / 60_000;
+                if (dt > 0 && delta > 0)
+                    setRate(delta / dt);
+                if (delta > 0) {
+                    setSeries((arr) => {
+                        const next = arr.slice();
+                        next[next.length - 1] = (next[next.length - 1] ?? 0) + delta;
+                        return next;
+                    });
+                }
+                lastTotalRef.current = tot;
+                lastSampleAtRef.current = Date.now();
+                setStats({ ...s });
+            });
+        }
+        async function rescan() {
+            const active = findActiveTranscript();
+            if (active && active.path !== transcriptPath)
+                await attach(active.path);
+        }
+        rescan();
+        const interval = setInterval(rescan, RESCAN_MS);
+        return () => {
+            cancelled = true;
+            clearInterval(interval);
+            handle?.stop().catch(() => undefined);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const transcripts = listTranscripts().slice(0, 5);
+    return (_jsxs(Box, { flexDirection: "column", padding: 1, children: [_jsx(Header, { auth: auth }), _jsxs(Box, { marginTop: 1, flexDirection: "row", gap: 1, children: [_jsx(SessionPanel, { stats: stats, rate: rate, now: now, series: series }), _jsx(BreakdownPanel, { stats: stats })] }), _jsx(Box, { marginTop: 1, children: _jsx(TranscriptsPanel, { transcripts: transcripts, activePath: transcriptPath, now: now }) }), _jsx(Box, { marginTop: 1, children: _jsxs(Text, { dimColor: true, children: [_jsx(Text, { color: "magenta", children: "q" }), " quit \u00B7", ' ', _jsx(Text, { color: "magenta", children: "live" }), " tail of ~/.claude/projects \u00B7 pricing is", ' ', _jsx(Text, { italic: true, children: "API-equivalent" }), ", not your real bill on a subscription"] }) })] }));
+}
+// ── Header ───────────────────────────────────────────────────────────────────
+function Header({ auth }) {
+    const ok = auth.installed && auth.loggedIn;
+    const dot = ok ? 'green' : auth.installed ? 'yellow' : 'red';
+    const planChip = planChipFor(auth);
+    return (_jsxs(Box, { borderStyle: "round", borderColor: "cyan", paddingX: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, color: "cyan", children: "\u258C tokens-metric " }), _jsx(Text, { dimColor: true, children: "v0.1.0 \u2014 real-time Claude Code usage" })] }), _jsx(Box, { marginTop: 0, children: _jsxs(Text, { children: [_jsx(Text, { color: dot, children: "\u25CF" }), ' ', auth.installed ? 'Claude Code detected' : 'Claude Code NOT detected', '   ', _jsx(Text, { ...planChip.style, children: planChip.label }), auth.userIdShort && _jsx(Text, { dimColor: true, children: `   user ${auth.userIdShort}` })] }) }), auth.hint && (_jsx(Box, { children: _jsxs(Text, { dimColor: true, children: ["\u21B3 ", auth.hint] }) }))] }));
+}
+function planChipFor(auth) {
+    if (!auth.loggedIn)
+        return { label: ' LOGGED-OUT ', style: { color: 'red', bold: true } };
+    switch (auth.planHint) {
+        case 'api':
+            return { label: ' API ', style: { color: 'yellow', bold: true } };
+        case 'team-or-enterprise':
+            return { label: ' TEAM / ENTERPRISE ', style: { color: 'magenta', bold: true } };
+        case 'paid':
+            return { label: ' PRO / MAX ', style: { color: 'green', bold: true } };
+        case 'free':
+            return { label: ' FREE ', style: { color: 'blue', bold: true } };
+        default:
+            return { label: ' SUBSCRIPTION ', style: { color: 'cyan', bold: true } };
+    }
+}
+// ── Session panel ────────────────────────────────────────────────────────────
+function SessionPanel({ stats, rate, now, series, }) {
+    return (_jsxs(Box, { borderStyle: "round", borderColor: "green", paddingX: 1, flexDirection: "column", flexGrow: 1, minWidth: 42, children: [_jsx(Text, { bold: true, color: "green", children: "Active session" }), !stats ? (_jsx(Text, { dimColor: true, children: "Waiting for a Claude Code session\u2026" })) : (_jsxs(_Fragment, { children: [_jsx(KV, { k: "Model", v: _jsx(Text, { color: "cyan", children: stats.lastModel ?? '—' }) }), _jsx(KV, { k: "Msgs ", v: _jsx(Text, { children: stats.messageCount }) }), _jsx(KV, { k: "Last ", v: stats.lastEventAt ? (_jsxs(Text, { children: [timeAgo(now - stats.lastEventAt), " ago"] })) : (_jsx(Text, { dimColor: true, children: "\u2014" })) }), _jsx(KV, { k: "cwd  ", v: _jsx(Text, { dimColor: true, wrap: "truncate-middle", children: stats.cwd ?? '—' }) }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { bold: true, children: "\u03A3 " }), _jsx(Text, { color: "cyan", bold: true, children: fmtNumber(totalTokens(stats.totals)) }), _jsx(Text, { dimColor: true, children: " tokens" })] }), (() => {
+                                const cost = estimateCostUSD(stats.lastModel ?? '', stats.totals);
+                                return cost !== null ? (_jsxs(Text, { dimColor: true, children: ["~", fmtUSD(cost), " API-equivalent"] })) : null;
+                            })(), _jsxs(Text, { children: [_jsx(Text, { bold: true, children: "~ " }), _jsx(Text, { color: "yellow", children: fmtNumber(Math.round(rate)) }), _jsx(Text, { dimColor: true, children: " tok/min" })] })] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { dimColor: true, children: ["activity (last ", SPARK_WIDTH, "s)"] }), _jsx(Text, { color: "yellow", children: sparkline(series, SPARK_WIDTH) })] })] }))] }));
+}
+// ── Breakdown panel ──────────────────────────────────────────────────────────
+function BreakdownPanel({ stats }) {
+    return (_jsxs(Box, { borderStyle: "round", borderColor: "blue", paddingX: 1, flexDirection: "column", flexGrow: 1, minWidth: 42, children: [_jsx(Text, { bold: true, color: "blue", children: "Token breakdown" }), !stats ? (_jsx(Text, { dimColor: true, children: "No data yet." })) : ((() => {
+                const u = stats.totals;
+                const max = Math.max(1, u.input_tokens, u.output_tokens, u.cache_creation_input_tokens, u.cache_read_input_tokens);
+                return (_jsxs(Box, { flexDirection: "column", children: [_jsx(BarRow, { label: "Input    ", value: u.input_tokens, max: max, color: "cyan" }), _jsx(BarRow, { label: "Output   ", value: u.output_tokens, max: max, color: "green" }), _jsx(BarRow, { label: "C. write ", value: u.cache_creation_input_tokens, max: max, color: "yellow" }), _jsx(BarRow, { label: "C. read  ", value: u.cache_read_input_tokens, max: max, color: "magenta" }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "By model" }), Object.entries(stats.byModel).map(([m, mu]) => (_jsxs(Text, { children: [_jsx(Text, { color: "cyan", children: shortModel(m) }), _jsx(Text, { dimColor: true, children: "  \u03A3 " }), _jsx(Text, { children: fmtNumber(totalTokens(mu)) })] }, m)))] })] }));
+            })())] }));
+}
+function BarRow({ label, value, max, color, }) {
+    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)] })] }));
+}
+// ── Transcripts panel ────────────────────────────────────────────────────────
+function TranscriptsPanel({ transcripts, activePath, now, }) {
+    return (_jsxs(Box, { borderStyle: "round", borderColor: "gray", paddingX: 1, flexDirection: "column", width: "100%", children: [_jsx(Text, { bold: true, children: "Recent transcripts" }), transcripts.length === 0 ? (_jsx(Text, { dimColor: true, children: "None found under ~/.claude/projects" })) : (transcripts.map((t) => {
+                const isActive = t.path === activePath;
+                return (_jsxs(Text, { children: [_jsx(Text, { color: isActive ? 'green' : 'gray', children: isActive ? '▶ ' : '  ' }), _jsx(Text, { dimColor: !isActive, wrap: "truncate-middle", children: t.cwd }), _jsx(Text, { dimColor: true, children: `   ${timeAgo(now - t.mtimeMs)}` })] }, t.path));
+            }))] }));
+}
+// ── helpers ──────────────────────────────────────────────────────────────────
+function KV({ k, v }) {
+    return (_jsxs(Text, { children: [_jsx(Text, { bold: true, children: k }), _jsx(Text, { dimColor: true, children: " \u00B7 " }), v] }));
+}
+function shortModel(m) {
+    return m.replace(/^claude-/, '').replace(/-20\d{6}/, '').replace(/-\d{8}$/, '');
+}
+function timeAgo(ms) {
+    if (ms < 0)
+        ms = 0;
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h`;
+    return `${Math.floor(h / 24)}d`;
+}
+render(_jsx(App, {}));

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "tokens-metric",
+  "version": "0.1.0",
+  "description": "Real-time token usage meter for Claude Code — statusline + Ink TUI.",
+  "type": "module",
+  "bin": {
+    "tokens-metric": "dist/tui/index.js",
+    "tokens-metric-statusline": "dist/statusline/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev:tui": "tsx src/tui/index.tsx",
+    "dev:statusline": "tsx src/statusline/index.ts",
+    "start": "node dist/tui/index.js",
+    "statusline": "node dist/statusline/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "tokens",
+    "usage",
+    "statusline",
+    "tui",
+    "ink",
+    "monitor"
+  ],
+  "author": "Annibal48",
+  "license": "MIT",
+  "homepage": "https://github.com/Annibal48/Tokens-Metric#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Annibal48/Tokens-Metric.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Annibal48/Tokens-Metric/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "ink": "^5.0.1",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.7",
+    "@types/react": "^18.3.3",
+    "tsx": "^4.16.2",
+    "typescript": "^5.5.3"
+  }
+}