claude-token-counter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edward Honour
+
+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,294 @@
+# claude-token-counter
+
+A live terminal dashboard that tracks your **Claude Code** token usage and cost in
+near real time — plus span markers to measure a unit of work and rolling log
+files. Zero dependencies, one file, just Node.
+
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![node: >=20](https://img.shields.io/badge/node-%3E%3D20-339933.svg)
+![dependencies: none](https://img.shields.io/badge/dependencies-0-brightgreen.svg)
+
+```text
+ Claude Code Token Tracker                                              14:32:08
+────────────────────────────────────────────────────────────────────────────────
+ ▶ SPAN auth system  since 14:02:11  (29m 57s)
+   in 4,210  out 18,940  cache-r 1,402,883  cache-w 233,015
+   tokens 1,659,048   requests 11   cost $4.21
+
+ CURRENT SESSION  ·  my-api  ·  9f3c1a2b   ● live
+   in 5,279   out 75,542   cache-r 5,721,161   cache-w 585,706
+   requests 26   span 1h 48m   updated 7s ago   cost $10.63
+
+ TODAY  2026-06-15   tokens 7,197,622   requests 29   cost $13.52
+   model                   input    output     cache-r    cache-w       cost
+   opus-4-8               11,613    77,092   6,268,883    840,034      $13.52
+
+ ALL TIME   tokens 41,883,902   requests 612   cost $96.40
+   model                   input    output     cache-r    cache-w       cost
+   opus-4-8              198,221 1,402,944  38,902,113  1,279,624      $89.71
+   sonnet-4-6             12,004    88,210   1,902,556    410,338       $6.69
+
+ RECENT
+   14:32:01  opus-4-8     in       2  out  1,373  cr   277,762    $0.1821
+   14:31:39  opus-4-8     in       2  out    175  cr   276,853    $0.1519
+────────────────────────────────────────────────────────────────────────────────
+ 3 projects · 28 sessions · log:daily · keys m span  q quit
+```
+
+> Numbers above are illustrative.
+
+## Contents
+
+- [Why](#why)
+- [Features](#features)
+- [Requirements](#requirements)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [The dashboard](#the-dashboard)
+- [Spans — measuring a unit of work](#spans--measuring-a-unit-of-work)
+- [Logs](#logs)
+- [Configuration](#configuration)
+- [How it works](#how-it-works)
+- [Cost model](#cost-model)
+- [FAQ & notes](#faq--notes)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Why
+
+Claude Code doesn't show you a running total of what a piece of work *cost* — and
+if you want to know "how many tokens did building the auth system take?", there's
+nowhere to look. This tool reads Claude Code's own local session transcripts and
+turns them into a live dashboard, so you can watch usage accrue, break it down by
+model, and mark start/end points around a task to measure it exactly.
+
+It's a passive **reader** — it never touches the Claude Code request path, needs no
+API key, and nothing leaves your machine.
+
+## Features
+
+- **Live dashboard** — current session, today, and all-time totals, refreshed as
+  Claude Code works (instant on file change, with a 1-second backstop).
+- **Per-model breakdown** — Opus / Sonnet / Haiku / Fable, separately.
+- **Token detail** — input, output, cache-read, and cache-write, not just a single number.
+- **USD cost** — priced per model, with cache writes split into 5-minute vs 1-hour TTL for accuracy.
+- **Spans** — mark a start and end point to measure a unit of work (e.g. "the auth system").
+- **Logs** — append-only span history plus rolling daily / per-session usage reports.
+- **Zero dependencies** — a single Node file; `npx` and go.
+
+## Requirements
+
+- **Node.js ≥ 20** (uses recursive `fs.readdirSync` / `fs.watch`).
+- **Claude Code** installed and used at least once, so `~/.claude/projects/` exists.
+
+Works on macOS, Linux, and Windows (Windows Terminal / any ANSI-capable terminal).
+
+## Install
+
+Run without installing (recommended):
+
+```bash
+npx claude-token-counter
+```
+
+Install the command globally:
+
+```bash
+npm install -g claude-token-counter
+# provides both `claude-token-counter` and the short `claude-tokens`
+```
+
+No npm account needed — you can also run straight from this repo:
+
+```bash
+npx github:maludb/claude-token-counter
+```
+
+Or from a clone:
+
+```bash
+git clone https://github.com/maludb/claude-token-counter.git
+cd claude-token-counter
+node token-counter.js
+```
+
+## Quick start
+
+```bash
+claude-token-counter                 # launch the live dashboard
+# in another terminal, while you work in Claude Code:
+claude-token-counter mark start "auth system"
+#   ...build it...
+claude-token-counter mark end        # prints + logs the token/cost total
+```
+
+## The dashboard
+
+```bash
+claude-token-counter                 # live dashboard (alias: claude-tokens)
+claude-token-counter --once          # print one snapshot and exit
+claude-token-counter --log session   # rolling report per session (default: daily)
+NO_COLOR=1 claude-token-counter      # disable color
+```
+
+The **current session** is whichever transcript was most recently appended to, so
+the dashboard automatically follows your active Claude Code window. The `● live`
+badge means that session was active in the last 30 seconds.
+
+**Keys**
+
+| Key | Action |
+|-----|--------|
+| `m` | Start a span (prompts for a label) / stop the running span |
+| `q` or `Ctrl-C` | Quit |
+
+## Spans — measuring a unit of work
+
+A *span* marks a start and end point. Its total is the sum of token usage across
+every turn whose timestamp falls in that window — that's how you answer "how much
+did this task take?" State is shared between the dashboard and the CLI, so a span
+you start in one terminal shows up live in the other (and `m` in the dashboard does
+the same thing).
+
+```bash
+claude-token-counter mark start "auth system"   # begin measuring
+claude-token-counter mark status                 # live total of the running span
+claude-token-counter mark end                    # finish: print + log the total
+claude-token-counter mark list                   # recent finished spans
+claude-token-counter mark cancel                 # discard the running span (no log)
+```
+
+**Options**
+
+| Option | Applies to | Meaning |
+|--------|-----------|---------|
+| `--session <id>` | `mark start` | Count only that session's usage in the window (default: all sessions) |
+| `--force` | `mark start` | Replace an already-running span |
+
+Example `mark end` output:
+
+```text
+■ span "auth system" — 29m 57s
+  tokens 1,659,048  (in 4,210 · out 18,940 · cache-r 1,402,883 · cache-w 233,015)
+  cost $4.21  ·  11 requests across 1 session(s)
+  logged to ~/.claude-token-counter/logs/markers.log
+```
+
+> A span counts **all** Claude Code activity in its window. If you run unrelated
+> sessions at the same time, scope it with `--session <id>` for an exact figure.
+
+## Logs
+
+State and logs live under `~/.claude-token-counter` (override with `$CTC_DIR`).
+Run `claude-token-counter paths` to print the exact locations.
+
+| File | What |
+|------|------|
+| `markers.json` | Active + recently completed spans (the shared state file) |
+| `logs/markers.log` | One human-readable line per finished span (append-only) |
+| `logs/markers.jsonl` | The same span events as JSON, one per line — for scripts |
+| `logs/daily-YYYY-MM-DD.log` | Rolling daily usage report (totals, per-model, spans) |
+| `logs/session-<id>.log` | Same report per session (with `--log session` or `both`) |
+
+Rolling reports are refreshed (every ~60s and on exit) while the dashboard runs;
+`--log off` disables them. Span logs are written by `mark end` whether or not the
+dashboard is running.
+
+`markers.log` line:
+
+```text
+2026-06-15 14:32:08  auth system  29m 57s  (14:02:11→14:32:08)  in=4,210 out=18,940 cache_r=1,402,883 cache_w=233,015  total=1,659,048  cost=$4.2103  requests=11  sessions=1
+```
+
+`markers.jsonl` is machine-readable — total today's span spend with `jq`:
+
+```bash
+jq -s 'map(.cost_usd) | add' ~/.claude-token-counter/logs/markers.jsonl
+```
+
+## Configuration
+
+| Flag / env | Default | Meaning |
+|------------|---------|---------|
+| `--log <daily\|session\|both\|off>` | `daily` | Which rolling report to keep updated |
+| `--once` | — | Print one snapshot and exit (no logs written) |
+| `--dir <path>` / `$CTC_DIR` | `~/.claude-token-counter` | State + log directory |
+| `$NO_COLOR` | — | Any value disables ANSI color |
+
+Other commands: `claude-token-counter paths` (show file locations),
+`claude-token-counter --help`.
+
+## How it works
+
+Claude Code writes one JSONL transcript per session under
+`~/.claude/projects/<encoded-project>/<session-id>.jsonl`, appending a line for
+every turn. Each assistant turn carries a `message.usage` block:
+
+```json
+{
+  "input_tokens": 2951,
+  "output_tokens": 843,
+  "cache_read_input_tokens": 15582,
+  "cache_creation_input_tokens": 2444,
+  "cache_creation": { "ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 2444 }
+}
+```
+
+The tracker:
+
+1. **Tails** every transcript — repaints instantly on change via recursive
+   `fs.watch`, with a 1-second poll as a backstop, reading only newly-appended bytes.
+2. **Dedupes** turns by `message.id` + `requestId` (resumed/compacted sessions can
+   replay earlier messages).
+3. **Aggregates** into current-session, per-day, and all-time buckets, plus a flat
+   record list used to compute span windows.
+4. **Prices** each turn per model, splitting cache writes into 5-minute vs 1-hour
+   TTL using the `cache_creation` breakdown.
+
+No API key, no network, no write access to Claude Code's data.
+
+## Cost model
+
+USD per 1,000,000 tokens. Cache reads bill at 0.1× input; cache writes at 1.25×
+input (5-minute TTL) or 2× input (1-hour TTL). The transcript records the 5m/1h
+split, so writes are priced exactly rather than estimated.
+
+| Model | Input | Output | Cache read | Cache write 5m | Cache write 1h |
+|-------|-------|--------|------------|----------------|----------------|
+| Opus 4.8   | $5.00  | $25.00 | $0.50 | $6.25  | $10.00 |
+| Sonnet 4.6 | $3.00  | $15.00 | $0.30 | $3.75  | $6.00  |
+| Haiku 4.5  | $1.00  | $5.00  | $0.10 | $1.25  | $2.00  |
+| Fable 5    | $10.00 | $50.00 | $1.00 | $12.50 | $20.00 |
+
+Rates live in the `PRICES` table at the top of `token-counter.js` — edit there if
+they change.
+
+## FAQ & notes
+
+**Is this a bill?** No. It's the **list-price equivalent** of the tokens consumed.
+If you're on a Claude subscription (Pro/Max) rather than metered API billing, read
+it as "what this usage would cost at API rates," not an invoice.
+
+**Does it send my data anywhere?** No. It only reads local files under
+`~/.claude/projects/` and writes logs under `~/.claude-token-counter/`. Nothing
+leaves your machine.
+
+**Why is a span showing 0 tokens?** A span only captures turns that *complete*
+between its start and end. A span ended seconds after starting, with no Claude
+turn in between, is correctly 0.
+
+**Can Claude Code start spans for me?** Yes — `mark start` / `mark end` are plain
+shell commands, so you can run them yourself, alias them, or have Claude Code run them.
+
+**An unknown model shows $0.** Only Opus / Sonnet / Haiku / Fable are priced. Add a
+row to the `PRICES` table for anything else.
+
+## Contributing
+
+Issues and PRs welcome. The whole tool is one dependency-free file
+(`token-counter.js`); `node --check token-counter.js` and a quick
+`node token-counter.js --once` cover most smoke-testing.
+
+## License
+
+[MIT](LICENSE) © Edward Honour

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "claude-token-counter",
+  "version": "1.0.0",
+  "description": "Live terminal dashboard for Claude Code token usage and cost",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "anthropic",
+    "tokens",
+    "token-counter",
+    "usage",
+    "cost",
+    "cli",
+    "tui",
+    "terminal",
+    "dashboard"
+  ],
+  "homepage": "https://github.com/maludb/claude-token-counter#readme",
+  "bugs": {
+    "url": "https://github.com/maludb/claude-token-counter/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maludb/claude-token-counter.git"
+  },
+  "author": "Edward Honour <edward.honour@gmail.com>",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "claude-token-counter": "token-counter.js",
+    "claude-tokens": "token-counter.js"
+  },
+  "files": [
+    "token-counter.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node token-counter.js",
+    "once": "node token-counter.js --once"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/token-counter.js

@@ -0,0 +1,631 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Claude Code token tracker — a live terminal dashboard, span markers, and logs
+ * for your Claude Code token usage, read straight from the local transcripts.
+ *
+ * Claude Code appends one JSONL transcript per session under
+ *   ~/.claude/projects/<encoded-project>/<session-id>.jsonl
+ * Every assistant turn carries a `message.usage` block. We tail those files,
+ * dedupe by message/request id, aggregate, and render. No external deps.
+ *
+ * A "span" marks a start/end point so you can measure a unit of work
+ * (e.g. "the auth system"): its total is the sum of usage in that time window.
+ * State + logs live under ~/.claude-token-counter (override with $CTC_DIR).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// ---------------------------------------------------------------------------
+// Pricing — USD per 1,000,000 tokens.
+// Cache read = 0.1x input; cache write (5m) = 1.25x input; (1h) = 2x input.
+// ---------------------------------------------------------------------------
+const PRICES = [
+  { match: 'fable',  in: 10, out: 50 },
+  { match: 'opus',   in: 5,  out: 25 },
+  { match: 'sonnet', in: 3,  out: 15 },
+  { match: 'haiku',  in: 1,  out: 5  },
+];
+const UNKNOWN_PRICE = { in: 0, out: 0 };
+const PER = 1e6;
+
+function priceFor(model) {
+  const m = (model || '').toLowerCase();
+  for (const p of PRICES) if (m.includes(p.match)) return p;
+  return UNKNOWN_PRICE;
+}
+
+function costFor(model, u) {
+  const p = priceFor(model);
+  const input = u.input_tokens || 0;
+  const output = u.output_tokens || 0;
+  const cacheRead = u.cache_read_input_tokens || 0;
+  const cc = u.cache_creation || {};
+  let write5 = cc.ephemeral_5m_input_tokens || 0;
+  let write1 = cc.ephemeral_1h_input_tokens || 0;
+  if (!write5 && !write1) write5 = u.cache_creation_input_tokens || 0; // assume 5m
+  const cost =
+    (input * p.in + output * p.out + cacheRead * p.in * 0.1 +
+      write5 * p.in * 1.25 + write1 * p.in * 2.0) / PER;
+  return { input, output, cacheRead, cacheWrite: write5 + write1, cost };
+}
+
+// ---------------------------------------------------------------------------
+// Paths / state dir
+// ---------------------------------------------------------------------------
+const HOME = os.homedir();
+const PROJECTS_DIR = path.join(HOME, '.claude', 'projects');
+
+let BASE = process.env.CTC_DIR || path.join(HOME, '.claude-token-counter');
+let LOGS_DIR = path.join(BASE, 'logs');
+let MARKERS_FILE = path.join(BASE, 'markers.json');
+function setBase(dir) {
+  BASE = path.resolve(dir);
+  LOGS_DIR = path.join(BASE, 'logs');
+  MARKERS_FILE = path.join(BASE, 'markers.json');
+}
+function ensureDirs() { fs.mkdirSync(LOGS_DIR, { recursive: true }); }
+function atomicWrite(file, str) {
+  ensureDirs();
+  const tmp = file + '.tmp' + process.pid;
+  fs.writeFileSync(tmp, str);
+  fs.renameSync(tmp, file);
+}
+
+// ---------------------------------------------------------------------------
+// Ingest state
+// ---------------------------------------------------------------------------
+const files = new Map();    // path -> { offset, partial }
+const seen = new Set();     // dedupe keys
+const records = [];         // slim per-turn records, for span windows
+const sessions = new Map(); // sessionId -> bucket(+meta)
+const days = new Map();     // localDateKey -> bucket
+const allTime = newBucket();
+const feed = [];            // recent turns (newest kept)
+let latestTs = 0;
+let currentSessionId = null;
+let startedAt = Date.now();
+
+let LOG_MODE = 'daily';     // daily | session | both | off
+let markers = { active: null, completed: [] };
+let prompt = null;          // { buffer } when typing a span label in the TUI
+let flash = null;           // { msg, until }
+
+function newBucket() {
+  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, requests: 0, models: new Map() };
+}
+function addToBucket(b, model, r) {
+  b.input += r.input; b.output += r.output; b.cacheRead += r.cacheRead;
+  b.cacheWrite += r.cacheWrite; b.cost += r.cost; b.requests += 1;
+  let m = b.models.get(model);
+  if (!m) { m = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, requests: 0 }; b.models.set(model, m); }
+  m.input += r.input; m.output += r.output; m.cacheRead += r.cacheRead;
+  m.cacheWrite += r.cacheWrite; m.cost += r.cost; m.requests += 1;
+}
+function totalTokens(b) { return b.input + b.output + b.cacheRead + b.cacheWrite; }
+function localDateKey(d) {
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
+function processLine(line, fallbackSid) {
+  let o;
+  try { o = JSON.parse(line); } catch { return; }
+  if (o.type !== 'assistant') return;
+  const msg = o.message;
+  if (!msg || !msg.usage) return;
+  const model = msg.model;
+  if (!model || model.startsWith('<')) return;
+
+  const key = `${msg.id || ''}|${o.requestId || ''}`;
+  if (seen.has(key)) return;
+  seen.add(key);
+
+  const r = costFor(model, msg.usage);
+  const sid = o.sessionId || fallbackSid;
+  const ts = o.timestamp ? Date.parse(o.timestamp) : Date.now();
+  const project = o.cwd ? path.basename(o.cwd) : '?';
+
+  records.push({ ts, session: sid, input: r.input, output: r.output, cacheRead: r.cacheRead, cacheWrite: r.cacheWrite, cost: r.cost });
+
+  addToBucket(allTime, model, r);
+  const dk = localDateKey(new Date(ts));
+  let day = days.get(dk);
+  if (!day) { day = newBucket(); days.set(dk, day); }
+  addToBucket(day, model, r);
+
+  let s = sessions.get(sid);
+  if (!s) { s = newBucket(); s.firstTs = ts; s.project = project; s.id = sid; sessions.set(sid, s); }
+  s.lastTs = ts; s.project = project;
+  addToBucket(s, model, r);
+
+  feed.push({ ts, model, project, ...r });
+  if (feed.length > 6) { feed.sort((a, b) => a.ts - b.ts); feed.splice(0, feed.length - 6); }
+
+  if (ts >= latestTs) { latestTs = ts; currentSessionId = sid; }
+}
+
+function readChunk(p, start, end) {
+  const len = end - start;
+  if (len <= 0) return '';
+  const fd = fs.openSync(p, 'r');
+  try {
+    const buf = Buffer.allocUnsafe(len);
+    fs.readSync(fd, buf, 0, len, start);
+    return buf.toString('utf8');
+  } finally { fs.closeSync(fd); }
+}
+function ingestFile(p) {
+  let meta = files.get(p);
+  if (!meta) { meta = { offset: 0, partial: '' }; files.set(p, meta); }
+  let st;
+  try { st = fs.statSync(p); } catch { return; }
+  if (st.size < meta.offset) { meta.offset = 0; meta.partial = ''; }
+  if (st.size === meta.offset) return;
+  const chunk = readChunk(p, meta.offset, st.size);
+  meta.offset = st.size;
+  const data = meta.partial + chunk;
+  const lines = data.split('\n');
+  meta.partial = lines.pop();
+  const sid = path.basename(p, '.jsonl');
+  for (const line of lines) if (line.trim()) processLine(line, sid);
+}
+function discover() {
+  let entries;
+  try { entries = fs.readdirSync(PROJECTS_DIR, { recursive: true }); } catch { return []; }
+  const out = [];
+  for (const e of entries) if (typeof e === 'string' && e.endsWith('.jsonl')) out.push(path.join(PROJECTS_DIR, e));
+  return out;
+}
+function scan() { for (const p of discover()) ingestFile(p); }
+
+// ---------------------------------------------------------------------------
+// Spans (markers)
+// ---------------------------------------------------------------------------
+function loadMarkers() {
+  try {
+    const o = JSON.parse(fs.readFileSync(MARKERS_FILE, 'utf8'));
+    return { active: o.active || null, completed: Array.isArray(o.completed) ? o.completed : [] };
+  } catch { return { active: null, completed: [] }; }
+}
+function saveMarkers(m) { atomicWrite(MARKERS_FILE, JSON.stringify(m, null, 2) + '\n'); }
+
+function sumWindow(start, end, session) {
+  const a = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, requests: 0, sessions: new Set() };
+  for (const r of records) {
+    if (r.ts < start || r.ts > end) continue;
+    if (session && r.session !== session) continue;
+    a.input += r.input; a.output += r.output; a.cacheRead += r.cacheRead;
+    a.cacheWrite += r.cacheWrite; a.cost += r.cost; a.requests += 1; a.sessions.add(r.session);
+  }
+  return a;
+}
+function finishSpan(active, end) {
+  const a = sumWindow(active.start, end, active.session);
+  const e = {
+    label: active.label, start: active.start, end, session: active.session || null,
+    input: a.input, output: a.output, cacheRead: a.cacheRead, cacheWrite: a.cacheWrite,
+    cost: a.cost, requests: a.requests, sessions: a.sessions.size,
+    total: a.input + a.output + a.cacheRead + a.cacheWrite,
+  };
+  appendSpanLog(e);
+  return e;
+}
+function appendSpanLog(e) {
+  ensureDirs();
+  const line =
+    `${localDateKey(new Date(e.end))} ${hms(e.end)}  ${e.label}  ${dur(e.end - e.start)}  ` +
+    `(${hms(e.start)}→${hms(e.end)})  in=${fmtN(e.input)} out=${fmtN(e.output)} ` +
+    `cache_r=${fmtN(e.cacheRead)} cache_w=${fmtN(e.cacheWrite)}  total=${fmtN(e.total)}  ` +
+    `cost=${money(e.cost, 4)}  requests=${e.requests}  sessions=${e.sessions}\n`;
+  fs.appendFileSync(path.join(LOGS_DIR, 'markers.log'), line);
+  const obj = {
+    type: 'span', label: e.label,
+    start: new Date(e.start).toISOString(), end: new Date(e.end).toISOString(),
+    duration_seconds: Math.round((e.end - e.start) / 1000),
+    input: e.input, output: e.output, cache_read: e.cacheRead, cache_write: e.cacheWrite,
+    total_tokens: e.total, cost_usd: Number(e.cost.toFixed(6)),
+    requests: e.requests, sessions: e.sessions, session: e.session,
+  };
+  fs.appendFileSync(path.join(LOGS_DIR, 'markers.jsonl'), JSON.stringify(obj) + '\n');
+}
+
+// ---------------------------------------------------------------------------
+// Rolling reports (daily / session)
+// ---------------------------------------------------------------------------
+function rollupText(title, subtitle, bucket, spans) {
+  const L = [title];
+  if (subtitle) L.push(subtitle);
+  L.push('updated: ' + localDateKey(new Date()) + ' ' + hms(Date.now()), '');
+  L.push(`TOTAL  tokens ${fmtN(totalTokens(bucket))}  requests ${fmtN(bucket.requests)}  cost ${money(bucket.cost, 4)}`);
+  L.push(`  input ${fmtN(bucket.input)} · output ${fmtN(bucket.output)} · cache-read ${fmtN(bucket.cacheRead)} · cache-write ${fmtN(bucket.cacheWrite)}`, '');
+  L.push('By model');
+  const rows = [...bucket.models.entries()].sort((a, b) => b[1].cost - a[1].cost);
+  if (!rows.length) L.push('  (none)');
+  for (const [m, v] of rows)
+    L.push(`  ${shortModel(m).padEnd(14)} in ${fmtN(v.input)}  out ${fmtN(v.output)}  cache-r ${fmtN(v.cacheRead)}  cache-w ${fmtN(v.cacheWrite)}  ${money(v.cost, 2)}`);
+  L.push('', 'Completed spans');
+  if (!spans.length) L.push('  (none)');
+  for (const e of spans)
+    L.push(`  ${hms(e.start)}→${hms(e.end)}  ${e.label}   ${fmtN(e.total)} tokens  ${money(e.cost, 2)}`);
+  L.push('');
+  return L.join('\n');
+}
+function writeRollupSafe() {
+  try {
+    if (LOG_MODE === 'off') return;
+    if (LOG_MODE === 'daily' || LOG_MODE === 'both') {
+      const key = localDateKey(new Date());
+      const b = days.get(key) || newBucket();
+      const spans = (markers.completed || []).filter(e => localDateKey(new Date(e.end)) === key);
+      atomicWrite(path.join(LOGS_DIR, `daily-${key}.log`), rollupText('Claude Code token usage — daily report', 'date: ' + key, b, spans));
+    }
+    if ((LOG_MODE === 'session' || LOG_MODE === 'both') && currentSessionId) {
+      const s = sessions.get(currentSessionId);
+      if (s) {
+        const spans = (markers.completed || []).filter(e => e.session === currentSessionId);
+        atomicWrite(path.join(LOGS_DIR, `session-${currentSessionId}.log`),
+          rollupText('Claude Code token usage — session report', `session: ${currentSessionId} (${s.project})`, s, spans));
+      }
+    }
+  } catch { /* logging must never crash the tracker */ }
+}
+
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const sgr = (code, s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+const dim = s => sgr('2', s);
+const bold = s => sgr('1', s);
+const green = s => sgr('32', s);
+const cyan = s => sgr('36', s);
+const yellow = s => sgr('33', s);
+const mag = s => sgr('35', s);
+
+function fmtN(n) { return Math.round(n).toLocaleString('en-US'); }
+function money(n, dp) {
+  if (dp == null) dp = n < 10 ? 4 : 2;
+  return '$' + n.toLocaleString('en-US', { minimumFractionDigits: dp, maximumFractionDigits: dp });
+}
+function shortModel(m) { return m.replace(/^claude-/, '').replace(/\[1m\]$/, '').replace(/-\d{8}$/, ''); }
+function hms(ts) { return new Date(ts).toLocaleTimeString('en-US', { hour12: false }); }
+function rel(ts) {
+  const s = Math.max(0, Math.round((Date.now() - ts) / 1000));
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+  return `${Math.floor(s / 86400)}d ago`;
+}
+function dur(ms) {
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ${s % 60}s`;
+  return `${Math.floor(s / 3600)}h ${Math.floor((s % 3600) / 60)}m`;
+}
+
+// ---------------------------------------------------------------------------
+// Dashboard rendering
+// ---------------------------------------------------------------------------
+function width() { return Math.min(process.stdout.columns || 80, 80); }
+function rule() { return dim('─'.repeat(width())); }
+
+function modelTable(bucket, pad) {
+  pad = pad || '   ';
+  const lines = [];
+  const head = 'model'.padEnd(18) + 'input'.padStart(11) + 'output'.padStart(10) +
+    'cache-r'.padStart(12) + 'cache-w'.padStart(11) + 'cost'.padStart(11);
+  lines.push(pad + dim(head));
+  for (const [model, m] of [...bucket.models.entries()].sort((a, b) => b[1].cost - a[1].cost)) {
+    lines.push(pad +
+      shortModel(model).slice(0, 17).padEnd(18) + fmtN(m.input).padStart(11) +
+      fmtN(m.output).padStart(10) + fmtN(m.cacheRead).padStart(12) +
+      fmtN(m.cacheWrite).padStart(11) + money(m.cost, 2).padStart(11));
+  }
+  return lines;
+}
+
+function render() {
+  const L = [];
+  const now = new Date();
+
+  const titlePlain = ' Claude Code Token Tracker';
+  const clock = now.toLocaleTimeString('en-US', { hour12: false });
+  const gap = Math.max(1, width() - titlePlain.length - clock.length);
+  L.push(bold(cyan(titlePlain)) + ' '.repeat(gap) + dim(clock));
+  L.push(rule());
+
+  // Active span (or last completed)
+  if (markers.active) {
+    const mk = markers.active;
+    const a = sumWindow(mk.start, Date.now(), mk.session);
+    const tot = a.input + a.output + a.cacheRead + a.cacheWrite;
+    L.push(' ' + bold(green('▶ SPAN ')) + yellow(mk.label) +
+      dim('  since ' + hms(mk.start) + '  (' + dur(Date.now() - mk.start) + ')') +
+      (mk.session ? dim('  · session ' + mk.session.slice(0, 8)) : ''));
+    L.push('   ' + dim('in ') + bold(fmtN(a.input)) + '  ' + dim('out ') + bold(fmtN(a.output)) +
+      '  ' + dim('cache-r ') + bold(fmtN(a.cacheRead)) + '  ' + dim('cache-w ') + bold(fmtN(a.cacheWrite)));
+    L.push('   ' + dim('tokens ') + bold(fmtN(tot)) + '   ' + dim('requests ') + bold(fmtN(a.requests)) +
+      '   ' + dim('cost ') + green(money(a.cost)));
+    L.push('');
+  } else if (markers.completed && markers.completed[0]) {
+    const e = markers.completed[0];
+    L.push(' ' + dim('last span: ') + e.label + dim('  ' + fmtN(e.total) + ' tokens · ' + money(e.cost)) + '');
+    L.push('');
+  }
+
+  // Current session
+  const cs = currentSessionId && sessions.get(currentSessionId);
+  if (cs) {
+    const live = Date.now() - cs.lastTs < 30000;
+    L.push(' ' + bold('CURRENT SESSION') + dim('  ·  ') + yellow(cs.project) +
+      dim('  ·  ') + dim((cs.id || '').slice(0, 8)) + '   ' + (live ? green('● live') : dim('○ idle')));
+    L.push('   ' + dim('in ') + bold(fmtN(cs.input)) + '   ' + dim('out ') + bold(fmtN(cs.output)) +
+      '   ' + dim('cache-r ') + bold(fmtN(cs.cacheRead)) + '   ' + dim('cache-w ') + bold(fmtN(cs.cacheWrite)));
+    L.push('   ' + dim('requests ') + bold(fmtN(cs.requests)) + '   ' + dim('span ') + bold(dur(cs.lastTs - cs.firstTs)) +
+      '   ' + dim('updated ') + bold(rel(cs.lastTs)) + '   ' + dim('cost ') + green(money(cs.cost)));
+  } else {
+    L.push(' ' + dim('No session activity recorded yet — waiting for usage…'));
+  }
+  L.push('');
+
+  const today = days.get(localDateKey(now)) || newBucket();
+  L.push(' ' + bold('TODAY') + dim('  ' + localDateKey(now)) + '   ' + dim('tokens ') + bold(fmtN(totalTokens(today))) +
+    '   ' + dim('requests ') + bold(fmtN(today.requests)) + '   ' + dim('cost ') + green(money(today.cost)));
+  if (today.models.size) L.push(...modelTable(today));
+  L.push('');
+
+  L.push(' ' + bold('ALL TIME') + '   ' + dim('tokens ') + bold(fmtN(totalTokens(allTime))) +
+    '   ' + dim('requests ') + bold(fmtN(allTime.requests)) + '   ' + dim('cost ') + green(money(allTime.cost)));
+  if (allTime.models.size) L.push(...modelTable(allTime));
+  L.push('');
+
+  if (feed.length) {
+    L.push(' ' + dim('RECENT'));
+    for (let i = feed.length - 1; i >= 0; i--) {
+      const f = feed[i];
+      L.push('   ' + dim(hms(f.ts)) + '  ' + mag(shortModel(f.model).padEnd(12)) + ' ' +
+        dim('in ') + fmtN(f.input).padStart(7) + '  ' + dim('out ') + fmtN(f.output).padStart(6) + '  ' +
+        dim('cr ') + fmtN(f.cacheRead).padStart(9) + '  ' + green(money(f.cost).padStart(9)));
+    }
+    L.push('');
+  }
+
+  L.push(rule());
+  if (prompt) {
+    L.push(' ' + bold(green('label this span: ')) + prompt.buffer + (useColor ? '\x1b[7m \x1b[0m' : '_') +
+      dim('   (Enter to start · Esc to cancel)'));
+  } else {
+    if (flash && Date.now() < flash.until) L.push(' ' + yellow(flash.msg));
+    L.push(' ' + dim(`${countProjects()} projects · ${sessions.size} sessions · log:${LOG_MODE} · `) +
+      dim('keys ') + bold('m') + dim(' span  ') + bold('q') + dim(' quit'));
+  }
+  return L;
+}
+function countProjects() {
+  const set = new Set();
+  for (const p of files.keys()) set.add(path.dirname(p));
+  return set.size;
+}
+
+// ---------------------------------------------------------------------------
+// Terminal driver
+// ---------------------------------------------------------------------------
+function draw() {
+  const lines = render();
+  const rows = (process.stdout.rows || 50) - 1;
+  process.stdout.write('\x1b[H' + lines.slice(0, rows).join('\x1b[K\n') + '\x1b[K\x1b[0J');
+}
+function enterAlt() { process.stdout.write('\x1b[?1049h\x1b[?25l\x1b[2J\x1b[H'); }
+function leaveAlt() { process.stdout.write('\x1b[?25h\x1b[?1049l'); }
+function setFlash(msg) { flash = { msg, until: Date.now() + 5000 }; }
+function quit(code) {
+  writeRollupSafe();
+  if (process.stdin.isTTY) { try { process.stdin.setRawMode(false); } catch {} }
+  if (process.stdout.isTTY) leaveAlt();
+  process.exit(code || 0);
+}
+
+function tuiStart(label) {
+  markers = loadMarkers();
+  if (markers.active) { setFlash('a span is already running'); return; }
+  markers.active = { label: label || ('span @ ' + hms(Date.now())), start: Date.now(), session: null };
+  saveMarkers(markers);
+  setFlash('▶ span started: ' + markers.active.label);
+}
+function tuiStop() {
+  markers = loadMarkers();
+  if (!markers.active) { setFlash('no active span'); return; }
+  const e = finishSpan(markers.active, Date.now());
+  markers.completed.unshift(e);
+  markers.completed = markers.completed.slice(0, 50);
+  markers.active = null;
+  saveMarkers(markers);
+  writeRollupSafe();
+  setFlash(`■ ${e.label}: ${fmtN(e.total)} tokens, ${money(e.cost)}`);
+}
+
+// ---------------------------------------------------------------------------
+// CLI: spans
+// ---------------------------------------------------------------------------
+function takeOpt(argv, name) { const i = argv.indexOf(name); if (i >= 0) { const v = argv[i + 1]; argv.splice(i, 2); return v; } return undefined; }
+function takeFlag(argv, name) { const i = argv.indexOf(name); if (i >= 0) { argv.splice(i, 1); return true; } return false; }
+
+function handleMark(argv) {
+  ensureDirs();
+  const sub = argv.shift();
+  const session = takeOpt(argv, '--session');
+  const force = takeFlag(argv, '--force');
+  const label = argv.join(' ').trim();
+  const m = loadMarkers();
+
+  if (sub === 'start' || sub === 'begin') {
+    if (m.active && !force) {
+      console.error(`A span "${m.active.label}" is already running (started ${hms(m.active.start)}, ${dur(Date.now() - m.active.start)} ago).`);
+      console.error('Finish it with "mark end", or replace it with "mark start --force <label>".');
+      process.exit(1);
+    }
+    m.active = { label: label || ('span @ ' + hms(Date.now())), start: Date.now(), session: session || null };
+    saveMarkers(m);
+    console.log(`▶ span started: ${m.active.label}${session ? ` (session ${session})` : ''}`);
+    console.log('  run "claude-token-counter mark end" when the work is done.');
+    return;
+  }
+  if (sub === 'end' || sub === 'stop') {
+    if (!m.active) { console.error('No active span. Start one with: mark start <label>'); process.exit(1); }
+    scan();
+    const e = finishSpan(m.active, Date.now());
+    m.completed.unshift(e); m.completed = m.completed.slice(0, 50); m.active = null; saveMarkers(m);
+    console.log(`■ span "${e.label}" — ${dur(e.end - e.start)}`);
+    console.log(`  tokens ${fmtN(e.total)}  (in ${fmtN(e.input)} · out ${fmtN(e.output)} · cache-r ${fmtN(e.cacheRead)} · cache-w ${fmtN(e.cacheWrite)})`);
+    console.log(`  cost ${money(e.cost)}  ·  ${fmtN(e.requests)} requests across ${e.sessions} session(s)`);
+    console.log(`  logged to ${path.join(LOGS_DIR, 'markers.log')}`);
+    return;
+  }
+  if (sub === 'cancel') {
+    if (!m.active) { console.log('No active span.'); return; }
+    const lbl = m.active.label; m.active = null; saveMarkers(m);
+    console.log(`span "${lbl}" cancelled (nothing logged).`);
+    return;
+  }
+  if (sub === 'status') {
+    if (!m.active) {
+      console.log('No active span.');
+      if (m.completed[0]) console.log(`Last: "${m.completed[0].label}" — ${fmtN(m.completed[0].total)} tokens, ${money(m.completed[0].cost)}`);
+      return;
+    }
+    scan();
+    const a = sumWindow(m.active.start, Date.now(), m.active.session);
+    const tot = a.input + a.output + a.cacheRead + a.cacheWrite;
+    console.log(`▶ "${m.active.label}" running — ${dur(Date.now() - m.active.start)} (since ${hms(m.active.start)})`);
+    console.log(`  tokens ${fmtN(tot)}  cost ${money(a.cost)}  requests ${fmtN(a.requests)}  sessions ${a.sessions.size}`);
+    return;
+  }
+  if (sub === 'list') {
+    if (!m.completed.length) { console.log('No completed spans yet.'); return; }
+    for (const e of m.completed.slice(0, 20))
+      console.log(`${localDateKey(new Date(e.end))} ${hms(e.end)}  ${e.label.padEnd(24)}  ${fmtN(e.total).padStart(12)} tokens  ${money(e.cost, 2).padStart(10)}  (${dur(e.end - e.start)})`);
+    return;
+  }
+  console.error('Usage: claude-token-counter mark <start|end|status|list|cancel> [label] [--session ID] [--force]');
+  process.exit(1);
+}
+
+function printPaths() {
+  console.log('state dir : ' + BASE);
+  console.log('markers   : ' + MARKERS_FILE);
+  console.log('logs dir  : ' + LOGS_DIR);
+  console.log('  spans   : ' + path.join(LOGS_DIR, 'markers.log') + '  (+ markers.jsonl)');
+  console.log('  rollups : ' + path.join(LOGS_DIR, 'daily-YYYY-MM-DD.log') + '  / session-<id>.log');
+}
+
+function printHelp() {
+  process.stdout.write(
+`Claude Code token tracker
+
+Dashboard
+  claude-token-counter [--log <daily|session|both|off>] [--dir <path>]
+                                 live dashboard (default --log daily)
+  claude-token-counter --once    print one snapshot and exit (no logs written)
+  claude-token-counter paths     show where state and logs are stored
+
+Spans — measure a unit of work (e.g. "the auth system")
+  claude-token-counter mark start <label>   begin measuring
+  claude-token-counter mark end             finish, print + log the total
+  claude-token-counter mark status          live total of the running span
+  claude-token-counter mark list            recent finished spans
+  claude-token-counter mark cancel          discard the running span
+    options: --session <id>  limit a span to one session
+             --force         replace an already-running span (with start)
+
+Dashboard keys:  m = start/stop a span   ·   q / Ctrl-C = quit
+Env: NO_COLOR=1 disables color · CTC_DIR overrides the state dir
+State dir: ${BASE}
+Reads transcripts from: ${PROJECTS_DIR}
+`);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+function main() {
+  const argv = process.argv.slice(2);
+
+  const dir = takeOpt(argv, '--dir') || process.env.CTC_DIR;
+  if (dir) setBase(dir);
+
+  const cmd = argv[0];
+  if (cmd === 'mark') return handleMark(argv.slice(1));
+  if (cmd === 'paths' || cmd === 'where') return printPaths();
+  if (cmd === '--help' || cmd === '-h' || cmd === 'help') return printHelp();
+
+  const once = takeFlag(argv, '--once');
+  const lm = takeOpt(argv, '--log');
+  if (lm) {
+    if (!['daily', 'session', 'both', 'off'].includes(lm)) {
+      console.error(`Invalid --log "${lm}". Use daily | session | both | off.`);
+      process.exit(1);
+    }
+    LOG_MODE = lm;
+  }
+
+  if (!fs.existsSync(PROJECTS_DIR)) {
+    process.stderr.write(`No Claude Code data found at ${PROJECTS_DIR}\n`);
+    process.exit(1);
+  }
+
+  startedAt = Date.now();
+  scan();
+  markers = loadMarkers();
+
+  if (once) { process.stdout.write(render().join('\n') + '\n'); return; }
+
+  if (!process.stdout.isTTY) {
+    setInterval(() => { scan(); markers = loadMarkers(); writeRollupSafe(); process.stdout.write(render().join('\n') + '\n\n'); }, 1000);
+    return;
+  }
+
+  ensureDirs();
+  writeRollupSafe();
+  enterAlt();
+  draw();
+
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.on('data', (buf) => {
+    const k = buf.toString();
+    if (prompt) {
+      if (k === '') return quit(0);
+      if (k === '\r' || k === '\n') { const l = prompt.buffer.trim(); prompt = null; tuiStart(l); return draw(); }
+      if (k === '') { prompt = null; setFlash('span start cancelled'); return draw(); }
+      if (k === '' || k === '\b') { prompt.buffer = prompt.buffer.slice(0, -1); return draw(); }
+      if (/^[\x20-\x7e]+$/.test(k)) { prompt.buffer += k; return draw(); }
+      return;
+    }
+    if (k === 'q' || k === '') return quit(0);
+    if (k === 'm') {
+      markers = loadMarkers();
+      if (markers.active) { tuiStop(); } else { prompt = { buffer: '' }; }
+      return draw();
+    }
+  });
+
+  process.on('SIGINT', () => quit(0));
+  process.on('SIGTERM', () => quit(0));
+  process.stdout.on('resize', draw);
+
+  setInterval(() => { scan(); markers = loadMarkers(); draw(); }, 1000);
+  setInterval(writeRollupSafe, 60000);
+
+  let pending = null;
+  try {
+    fs.watch(PROJECTS_DIR, { recursive: true }, () => {
+      if (pending) return;
+      pending = setTimeout(() => { pending = null; scan(); markers = loadMarkers(); draw(); }, 120);
+    });
+  } catch { /* recursive watch unsupported — 1s poll still covers it */ }
+}
+
+main();