@ryandemelo/token-monitor 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan
+
+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,208 @@
+# token-monitor
+
+[![CI](https://github.com/ryandemelo/token-monitor/actions/workflows/ci.yml/badge.svg)](https://github.com/ryandemelo/token-monitor/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Measure how effectively your team spends AI coding-agent tokens — locally, with zero setup.
+
+Most token dashboards tell you *how much* you spent. token-monitor tells you *what you spent it on* — separating thinking and defining from actual coding, testing, and shipping — and what to change. It parses the session logs that Claude Code, Gemini CLI, Codex, Cursor, Antigravity, and Copilot Chat already write to your machine. No API keys, no server, no telemetry.
+
+```
+Where the tokens go (activity share of input+output)
+
+  thinking      ████████░░░░░░░░░░░░░░░░  31.5%  33.5M   18087
+  exploration   ████░░░░░░░░░░░░░░░░░░░░  18.0%  19.1M   19067
+  coding        █████░░░░░░░░░░░░░░░░░░░  21.6%  22.9M    7351
+  testing       ░░░░░░░░░░░░░░░░░░░░░░░░   1.2%   1.3M    1407
+  shipping      █░░░░░░░░░░░░░░░░░░░░░░░   2.7%   2.8M    2064
+
+  rework ratio 17.1%  ·  think:code 2.30
+
+  Project        Tokens  Cost      Cache  Rework  Persona
+  ────────────   ──────  ────────  ─────  ──────  ───────────
+  checkout-api   12.4M   $2104     97%    13%     📐 Architect
+  etl-pipeline    5.0M    $730     96%    60%     🚒 Firefighter
+```
+
+## Quick start
+
+Requires Node.js ≥ 24 (uses the built-in `node:sqlite` — zero runtime dependencies).
+
+```sh
+npx @ryandemelo/token-monitor collect   # scan local agent logs
+npx @ryandemelo/token-monitor report    # activity breakdown, personas, recommendations
+npx @ryandemelo/token-monitor html      # self-contained dashboard -> report.html
+```
+
+Persistent install: `npm install -g @ryandemelo/token-monitor`, then `token-monitor <command>`. For development: clone, `npm install && npm test`.
+
+### Or let your coding agent install it
+
+Paste this into Claude Code, Gemini CLI, or any coding agent:
+
+> Install token-monitor from https://github.com/ryandemelo/token-monitor (instructions in its AGENTS.md), run `collect` and `report`, and walk me through what my token usage says.
+
+The repo ships [`AGENTS.md`](AGENTS.md) and [`llms.txt`](llms.txt) so agents can install and operate it without guesswork.
+
+## What it measures
+
+| Metric | Why it matters |
+|---|---|
+| **Activity breakdown** | Each turn is classified by its tool calls: *thinking/defining* (plan mode, reasoning-only turns), *exploration* (read/search), *coding* (edits), *testing* (test runners), *shipping* (commit/push/PR), *conversation*. |
+| **Cache hit ratio** | Cache reads cost ~10% of fresh input — the single biggest cost lever. Low ratios point at session and prompt-structure problems. |
+| **Rework ratio** | Share of tokens spent on code/test turns *after* the first failed turn in a session. High rework usually means skipped planning. Distinct from `analyze`'s **fix iterations**, which counts testing→coding transitions — sessions that barely test can have high rework but zero visible fix loops. User-declined permission prompts are *not* counted as failures. |
+| **Think:code ratio** | Planning+exploration tokens per coding token. Too low correlates with high rework. |
+| **Model mix** | Premium-model tokens on turns a cheaper tier would handle. |
+| **Estimated cost** | API-equivalent USD from a built-in price table (`src/pricing.ts`). Non-Anthropic prices are placeholders marked `~` — edit to match your contract. |
+
+## Personas
+
+Aggregate metrics are assigned a behavioral archetype, each with tailored recommendations:
+
+| Persona | Signature |
+|---|---|
+| 📐 **Architect** | Plans up front, low rework downstream |
+| 🔪 **Surgeon** | High cache reuse, targeted exploration, minimal waste |
+| 🧭 **Explorer** | Most tokens go to reading/searching before changes land |
+| 🏃 **Sprinter** | Straight to code, minimal planning, rework eats the savings |
+| 🚒 **Firefighter** | Heavy test-fail-fix loops |
+| ⚖️ **Balanced** | No dominant pattern |
+
+Personas are computed per-project and overall, so one expensive workflow can't hide in the average.
+
+## Supported agents
+
+| Agent | Source | Status |
+|---|---|---|
+| **Claude Code** | `~/.claude/projects/**/*.jsonl` | ✅ Verified — per-turn tokens, cache split, model, tools, git branch |
+| **Gemini CLI** | `~/.gemini/tmp/*/chats/*.json` | ✅ Verified — per-turn tokens incl. thoughts, tool calls |
+| **Codex CLI** | `~/.codex/sessions/**/rollout-*.jsonl` | ⚠️ Experimental — diffs cumulative `token_count` events; verify against Codex's own usage screens |
+| **Cursor** | `Cursor/User/globalStorage/state.vscdb` (SQLite) | ✅ Verified — per-turn tokens on completed turns, tool calls, agent/chat sessions. Cursor doesn't persist cache tokens or the resolved backend model (Auto mode reports as `cursor-auto`) |
+| **Antigravity CLI** | `~/.gemini/antigravity-cli/conversations/*.db` (SQLite + protobuf) | ✅ Verified — per-call prompt/cached/output tokens, per-row model, tool steps, workspace + branch. Vendor-internal format: fails soft if the schema changes |
+| **Copilot Chat** (VS Code) | `Code/User/workspaceStorage/*/chatSessions/*` | ⚠️ Experimental — Copilot doesn't record token usage locally, so counts are **estimated** from text length (~4 chars/token) and models are suffixed `(est)`. Turn counts, timestamps, tools, and errors are real |
+
+Adapters skip gracefully when a tool isn't installed. The Cursor adapter reads only composer/bubble keys — never the auth entries that live in the same database.
+
+## Team usage
+
+### Remote rollout (lead → team)
+
+The lead hosts one config file anywhere (gist, internal wiki, S3) and sends one line — pasteable by the dev, an MDM/onboarding script, or their coding agent:
+
+```sh
+npx @ryandemelo/token-monitor init --from https://example.com/team-config.json
+```
+
+```jsonc
+// team-config.json
+{
+  "teamName": "acme-eng",
+  "push": { "type": "http", "url": "https://reports.example.com/token-monitor" },
+  // or: "push": { "type": "path", "dir": "/Volumes/shared/token-monitor" }
+  "scheduleHours": 24,
+  "windowDays": 30
+}
+```
+
+`init` saves the config, generates the signing keypair, runs the first collection, installs the recurring collect+push job (launchd on macOS, cron on Linux), and prints the dev's fingerprint for the lead's `keys.json`. From then on signed exports arrive on schedule; the lead runs `merge <files> --verify --keys keys.json`. `token-monitor schedule --remove` uninstalls.
+
+### Manual flow
+
+Each developer exports locally; the JSON contains aggregate metrics only (no prompts, no code, no file paths beyond project basenames), so it's safe to share:
+
+```sh
+# each developer (exports/ is gitignored — keep real metrics out of repos)
+mkdir -p exports
+token-monitor collect && token-monitor report --json > exports/$(whoami).json
+
+# team lead
+cat > team.yaml <<'EOF'
+alice: frontend
+bob: backend
+carol: data
+EOF
+token-monitor merge exports/*.json --team team.yaml
+```
+
+The team report shows per-discipline rollups: tokens, cost, cache hit, rework, think:code ratio, dominant activity, and persona — so you can see *which discipline* needs which intervention, not just a total bill.
+
+## Deep analysis & LLM-powered recommendations
+
+`token-monitor analyze` goes a level deeper than the report — which sessions and habits burn the tokens:
+
+- **Most expensive sessions** — turns, fix loops, avg context per turn, duration, dominant activity
+- **Fix-loop sessions** — testing→coding churn
+- **Context-heavy sessions** — average tokens fed per turn (context-bloat proxy)
+- **Tool error rates** — tools that keep failing
+
+Add `--llm` and the aggregates go to a coding agent you already have installed (`claude`, `gemini`, or `codex` — auto-detected, override with `--agent`), which returns prioritized interventions with the evidence, the workflow change, and the metric to watch:
+
+```sh
+token-monitor analyze --llm
+```
+
+No API key management: it reuses your existing agent CLI and its subscription. The payload is the same aggregates-only data as `report --json` (token counts, ratios, tool names, project basenames — never prompts or code). It does leave your machine via that agent's provider, so skip `--llm` if even project names are sensitive.
+
+## Follow-through
+
+Recommendations are tracked, not just printed. The first time one fires, its target metric is recorded as a baseline; every later report re-measures and shows the delta:
+
+```
+Recommendation         Metric         Baseline  Now   Since       Status
+high-rework            reworkRatio    24%       11%   2026-06-01  ✅ resolved
+premium-model-overuse  premiumShare   99%       97%   2026-06-12  — tracking
+```
+
+Resolved findings re-open automatically if the metric regresses.
+
+## CLI
+
+```
+token-monitor collect [--source claude-code|gemini-cli|codex|cursor|antigravity|copilot] [--db <path>]
+token-monitor report  [--days 30] [--project <name>] [--source <name>] [--json] [--db <path>]
+token-monitor analyze [--days 30] [--llm] [--agent claude|gemini|codex] [--json] [--db <path>]
+token-monitor html    [--out report.html] [--days 30] [--db <path>]
+token-monitor merge   <export.json>... [--team team.yaml] [--json]
+```
+
+## Contributing
+
+The most valuable contribution: an adapter for another agent CLI (Aider, OpenCode, Cursor…). See [CONTRIBUTING.md](CONTRIBUTING.md) for the adapter guide, fixtures, and conventions. `npm test` runs the suite; CI covers Node 24/25 on Linux + macOS.
+
+## Roadmap
+
+- [x] Team rollups: `merge` command + `team.yaml` discipline mapping
+- [x] Self-contained HTML dashboard
+- [x] Follow-through tracking: baseline on first firing, delta on every later report
+- [x] IDE coverage: Cursor, Antigravity, Copilot Chat adapters
+- [ ] Adapters: Aider, OpenCode, Windsurf (needs a contributor with Windsurf — #12)
+- [ ] VS Code-family extension: status-bar cost + dashboard webview (#13)
+- [ ] Org-level cross-check via provider usage APIs
+- [x] npm publish: `npx @ryandemelo/token-monitor`
+
+## Integrity & threat model
+
+Exports are **tamper-evident**. Each machine generates an Ed25519 keypair on first export (`~/.token-monitor/signing-key.pem`, mode 0600); `report --json` signs a canonical serialization of the payload. The team lead verifies on merge:
+
+```sh
+# dev, once: print fingerprint for enrollment
+token-monitor fingerprint            # e.g. 3f9a1c0b2d4e5f67
+
+# lead: pin who may sign for whom (keys.json), then verify on every merge
+echo '{"alice": "3f9a1c0b2d4e5f67"}' > keys.json
+token-monitor merge exports/*.json --verify --keys keys.json
+```
+
+`--verify` rejects any export modified after signing or unsigned; `--keys` additionally rejects exports signed by a key not enrolled for that username (impersonation).
+
+**What this does not cover — read before relying on it:** a developer controls their own machine, so someone determined to game metrics could edit the *source logs* before collection. Signing detects tampering after export, not dishonest inputs. The planned mitigation is reconciling team totals against the provider's billing/usage APIs (roadmap) — gamed numbers won't reconcile. Treat these metrics as a coaching instrument, not a performance-review weapon; the latter invites exactly the gaming this can't stop.
+
+## Privacy
+
+Everything stays on your machine. token-monitor reads log files locally, stores aggregate numbers in a local SQLite file, and never makes a network request. Prompt and code content is never stored — only token counts, tool names, timestamps, and project/branch names.
+
+The one opt-in exception: `analyze --llm` sends those aggregates to your own agent CLI's provider for analysis. Everything else is fully offline.
+
+## License
+
+MIT

package/dist/src/adapters/antigravity.js

@@ -0,0 +1,197 @@
+import { readdirSync, existsSync, copyFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+import { DatabaseSync } from 'node:sqlite';
+import { classify } from '../classify.js';
+import { decodeMessage, intField, strField, msgField, msgFields } from './../protowire.js';
+/**
+ * Antigravity CLI stores one SQLite db per conversation under
+ * ~/.gemini/antigravity-cli/conversations/<id>.db. The interesting table is
+ * gen_metadata: one protobuf blob per LLM call, with token usage, model id,
+ * and timestamps. The steps table records turn/tool events; a gen row's
+ * "last step index at request time" lets us attribute the tool steps each
+ * generation produced. Field numbers were mapped empirically (issue #10) —
+ * the schema is vendor-internal, so everything here fails soft.
+ *
+ * Privacy: only usage/model/timing fields are decoded. The blobs also carry
+ * full prompt/conversation snapshots (f1.1/f1.2/f1.8/f1.16) — those are
+ * never descended into.
+ */
+const ROOT = join(homedir(), '.gemini', 'antigravity-cli');
+// steps.step_type -> normalized tool name (observed enum values)
+const STEP_TOOLS = {
+    8: 'view_file',
+    9: 'list_directory',
+    21: 'run_command',
+    23: 'update_plan',
+};
+// Non-tool step types: 14 = user input, 15 = planner response, 98 = history.
+const NON_TOOL_STEPS = new Set([14, 15, 98]);
+function tsToIso(msg) {
+    const sec = intField(msg, 1);
+    if (!sec)
+        return undefined;
+    return new Date(sec * 1000 + Math.floor(intField(msg, 2) / 1e6)).toISOString();
+}
+function collectConversation(dbPath, scratch, events) {
+    const convId = basename(dbPath, '.db');
+    const copy = join(scratch, `${convId}.db`);
+    copyFileSync(dbPath, copy);
+    for (const suffix of ['-wal', '-shm']) {
+        if (existsSync(dbPath + suffix))
+            copyFileSync(dbPath + suffix, copy + suffix);
+    }
+    const db = new DatabaseSync(copy);
+    try {
+        // Workspace / branch attribution.
+        let project = 'unknown';
+        let gitBranch;
+        try {
+            const row = db.prepare('SELECT data FROM trajectory_metadata_blob LIMIT 1').get();
+            if (row?.data) {
+                const ctx = msgField(decodeMessage(row.data), 1);
+                const workspaceUri = strField(ctx, 1);
+                if (workspaceUri)
+                    project = basename(decodeURIComponent(workspaceUri.replace(/^file:\/\//, '')));
+                gitBranch = strField(ctx, 4);
+            }
+        }
+        catch {
+            /* attribution is optional */
+        }
+        // Step events, for tool attribution per generation.
+        const steps = [];
+        try {
+            const rows = db
+                .prepare('SELECT idx, step_type, status, step_payload, error_details FROM steps ORDER BY idx')
+                .all();
+            for (const r of rows) {
+                const info = { idx: r.idx, type: r.step_type, status: r.status };
+                if (r.step_type === 21 && r.step_payload) {
+                    try {
+                        const payload = msgField(decodeMessage(r.step_payload), 28);
+                        info.command = strField(payload, 25) ?? strField(payload, 23);
+                    }
+                    catch { /* ignore */ }
+                }
+                if (r.status === 7 && r.error_details) {
+                    try {
+                        info.errorShort = strField(decodeMessage(r.error_details), 2);
+                    }
+                    catch { /* ignore */ }
+                }
+                steps.push(info);
+            }
+        }
+        catch {
+            /* steps are optional — events still carry tokens */
+        }
+        const genRows = db.prepare('SELECT idx, data FROM gen_metadata ORDER BY idx').all();
+        const gens = [];
+        for (const r of genRows) {
+            if (!r.data)
+                continue;
+            try {
+                const gen = msgField(decodeMessage(r.data), 1);
+                if (!gen)
+                    continue;
+                // f20 is a repeated {1: key, 2: value} annotation list; last_step_index
+                // is authoritative there (f6 is off by one from it).
+                let lastStep = intField(gen, 6) + 1;
+                for (const kv of msgFields(gen, 20)) {
+                    if (strField(kv, 1) === 'last_step_index') {
+                        const v = Number(strField(kv, 2));
+                        if (Number.isFinite(v))
+                            lastStep = v;
+                    }
+                }
+                gens.push({ idx: r.idx, lastStep, gen });
+            }
+            catch {
+                continue; // unknown layout — fail soft per row
+            }
+        }
+        gens.forEach(({ idx, lastStep, gen }, i) => {
+            const usage = msgField(gen, 4);
+            if (!usage)
+                return;
+            // Steps produced by this generation: after its request snapshot, up to
+            // the next generation's snapshot (or end of trajectory for the last).
+            const upper = i + 1 < gens.length ? gens[i + 1].lastStep : Number.MAX_SAFE_INTEGER;
+            const mySteps = steps.filter((s) => s.idx > lastStep && s.idx <= upper);
+            const tools = [];
+            const commands = [];
+            let isError = false;
+            for (const s of mySteps) {
+                if (NON_TOOL_STEPS.has(s.type))
+                    continue;
+                tools.push(STEP_TOOLS[s.type] ?? `step_${s.type}`);
+                if (s.command)
+                    commands.push(s.command);
+                // status 7 covers both failures and user cancellations — a cancel is a choice, not an error.
+                if (s.status === 7 && !/cancel/i.test(s.errorShort ?? ''))
+                    isError = true;
+            }
+            const timing = msgField(gen, 9);
+            const ev = {
+                source: 'antigravity',
+                eventKey: `${convId}:${idx}`,
+                sessionId: convId,
+                project,
+                timestamp: tsToIso(msgField(timing, 4)) ?? new Date(0).toISOString(),
+                model: strField(gen, 19) ?? strField(gen, 21) ?? 'antigravity',
+                inputTokens: intField(usage, 2),
+                outputTokens: intField(usage, 3),
+                cacheReadTokens: intField(usage, 5),
+                cacheCreationTokens: 0,
+                thinkingTokens: 0,
+                tools,
+                commands,
+                hasThinking: false,
+                isError,
+                gitBranch,
+            };
+            ev.activity = classify(ev);
+            events.push(ev);
+        });
+    }
+    finally {
+        db.close();
+    }
+}
+export function collectAntigravity(root = ROOT) {
+    const events = [];
+    const convDir = join(root, 'conversations');
+    if (!existsSync(convDir)) {
+        return { events, result: { source: 'antigravity', filesScanned: 0, eventsFound: 0, eventsInserted: 0, note: `${convDir} not found — Antigravity not detected` } };
+    }
+    const scratch = mkdtempSync(join(tmpdir(), 'tm-antigravity-'));
+    let filesScanned = 0;
+    let failed = 0;
+    try {
+        for (const file of readdirSync(convDir)) {
+            if (!file.endsWith('.db'))
+                continue;
+            filesScanned++;
+            try {
+                collectConversation(join(convDir, file), scratch, events);
+            }
+            catch {
+                failed++; // vendor-internal format — skip conversations we can't read
+            }
+        }
+    }
+    finally {
+        rmSync(scratch, { recursive: true, force: true });
+    }
+    return {
+        events,
+        result: {
+            source: 'antigravity',
+            filesScanned,
+            eventsFound: events.length,
+            eventsInserted: 0,
+            note: failed > 0 ? `${failed} conversation db(s) skipped (unreadable or unknown format)` : undefined,
+        },
+    };
+}

package/dist/src/adapters/claude-code.js

@@ -0,0 +1,121 @@
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { homedir } from 'node:os';
+import { classify } from '../classify.js';
+const ROOT = join(homedir(), '.claude', 'projects');
+/**
+ * User declinations arrive as is_error tool_results but are choices, not
+ * failures — counting them poisons tool-error and rework metrics. Matches
+ * the harness's standard rejection/interruption phrasings.
+ */
+const DECLINED_RE = /user doesn't want to proceed|tool use was rejected|user rejected|request interrupted by user|user declined/i;
+export function isDeclination(content) {
+    const text = typeof content === 'string'
+        ? content
+        : Array.isArray(content)
+            ? content.map((b) => (typeof b?.text === 'string' ? b.text : '')).join(' ')
+            : '';
+    return DECLINED_RE.test(text);
+}
+/** Parse Claude Code session transcripts: ~/.claude/projects/<dir>/<session>.jsonl */
+export function collectClaudeCode(root = ROOT) {
+    const events = [];
+    let filesScanned = 0;
+    if (!existsSync(root)) {
+        return { events, result: { source: 'claude-code', filesScanned: 0, eventsFound: 0, eventsInserted: 0, note: `${root} not found` } };
+    }
+    for (const dir of readdirSync(root)) {
+        const dirPath = join(root, dir);
+        let files;
+        try {
+            files = readdirSync(dirPath).filter((f) => f.endsWith('.jsonl'));
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            filesScanned++;
+            let text;
+            try {
+                text = readFileSync(join(dirPath, file), 'utf8');
+            }
+            catch {
+                continue;
+            }
+            // tool_use id -> event, so a failed tool_result can flag its turn
+            const byToolUseId = new Map();
+            for (const line of text.split('\n')) {
+                if (!line.trim())
+                    continue;
+                let d;
+                try {
+                    d = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (d.type === 'user' && Array.isArray(d.message?.content)) {
+                    for (const block of d.message.content) {
+                        if (block.type === 'tool_result' &&
+                            block.is_error &&
+                            block.tool_use_id &&
+                            !isDeclination(block.content)) {
+                            const ev = byToolUseId.get(block.tool_use_id);
+                            if (ev)
+                                ev.isError = true;
+                        }
+                    }
+                    continue;
+                }
+                if (d.type !== 'assistant' || !d.message?.usage || !d.uuid)
+                    continue;
+                const u = d.message.usage;
+                const total = (u.input_tokens ?? 0) + (u.output_tokens ?? 0);
+                if (total === 0 && !(u.cache_read_input_tokens || u.cache_creation_input_tokens))
+                    continue;
+                const tools = [];
+                const commands = [];
+                let hasThinking = false;
+                const toolUseIds = [];
+                for (const block of d.message.content ?? []) {
+                    if (block.type === 'tool_use' && block.name) {
+                        tools.push(block.name);
+                        if (block.id)
+                            toolUseIds.push(block.id);
+                        if (typeof block.input?.command === 'string')
+                            commands.push(block.input.command);
+                    }
+                    else if (block.type === 'thinking') {
+                        hasThinking = true;
+                    }
+                }
+                const ev = {
+                    source: 'claude-code',
+                    eventKey: d.uuid,
+                    sessionId: d.sessionId ?? file.replace('.jsonl', ''),
+                    project: d.cwd ? basename(d.cwd) : dir,
+                    timestamp: d.timestamp ?? new Date(0).toISOString(),
+                    model: d.message.model ?? 'unknown',
+                    inputTokens: u.input_tokens ?? 0,
+                    outputTokens: u.output_tokens ?? 0,
+                    cacheReadTokens: u.cache_read_input_tokens ?? 0,
+                    cacheCreationTokens: u.cache_creation_input_tokens ?? 0,
+                    thinkingTokens: 0,
+                    tools,
+                    commands,
+                    hasThinking,
+                    isError: false,
+                    gitBranch: d.gitBranch,
+                };
+                ev.activity = classify(ev);
+                events.push(ev);
+                for (const id of toolUseIds)
+                    byToolUseId.set(id, ev);
+            }
+        }
+    }
+    return {
+        events,
+        result: { source: 'claude-code', filesScanned, eventsFound: events.length, eventsInserted: 0 },
+    };
+}

package/dist/src/adapters/codex.js

@@ -0,0 +1,119 @@
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { homedir } from 'node:os';
+import { classify } from '../classify.js';
+const ROOT = join(homedir(), '.codex', 'sessions');
+function* walk(dir) {
+    for (const entry of readdirSync(dir)) {
+        const p = join(dir, entry);
+        if (statSync(p).isDirectory())
+            yield* walk(p);
+        else if (entry.startsWith('rollout-') && entry.endsWith('.jsonl'))
+            yield p;
+    }
+}
+export function collectCodex(root = ROOT) {
+    const events = [];
+    let filesScanned = 0;
+    if (!existsSync(root)) {
+        return { events, result: { source: 'codex', filesScanned: 0, eventsFound: 0, eventsInserted: 0, note: `${root} not found — Codex CLI not detected` } };
+    }
+    for (const file of walk(root)) {
+        filesScanned++;
+        let text;
+        try {
+            text = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        let sessionId = basename(file, '.jsonl');
+        let project = 'unknown';
+        let model = 'codex';
+        let prev = null;
+        let pendingTools = [];
+        let pendingCommands = [];
+        let tick = 0;
+        for (const line of text.split('\n')) {
+            if (!line.trim())
+                continue;
+            let d;
+            try {
+                d = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const p = d.payload;
+            if (!p)
+                continue;
+            if (d.type === 'session_meta' || p.type === 'session_meta') {
+                if (p.id)
+                    sessionId = p.id;
+                if (p.cwd)
+                    project = basename(p.cwd);
+            }
+            else if (p.type === 'turn_context' && p.model) {
+                model = p.model;
+            }
+            else if (d.type === 'response_item' && p.type === 'function_call' && p.name) {
+                pendingTools.push(p.name);
+                if (/shell|exec/.test(p.name) && typeof p.arguments === 'string') {
+                    try {
+                        const args = JSON.parse(p.arguments);
+                        const cmd = Array.isArray(args.command) ? args.command.join(' ') : args.command;
+                        if (typeof cmd === 'string')
+                            pendingCommands.push(cmd);
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+            else if (d.type === 'event_msg' && p.type === 'token_count' && p.info) {
+                const total = p.info.total_token_usage ?? p.info.last_token_usage;
+                if (!total)
+                    continue;
+                const delta = prev
+                    ? {
+                        input_tokens: Math.max(0, (total.input_tokens ?? 0) - (prev.input_tokens ?? 0)),
+                        cached_input_tokens: Math.max(0, (total.cached_input_tokens ?? 0) - (prev.cached_input_tokens ?? 0)),
+                        output_tokens: Math.max(0, (total.output_tokens ?? 0) - (prev.output_tokens ?? 0)),
+                        reasoning_output_tokens: Math.max(0, (total.reasoning_output_tokens ?? 0) - (prev.reasoning_output_tokens ?? 0)),
+                    }
+                    : total;
+                prev = total;
+                tick++;
+                const ev = {
+                    source: 'codex',
+                    eventKey: `${sessionId}:${tick}`,
+                    sessionId,
+                    project,
+                    timestamp: d.timestamp ?? new Date(0).toISOString(),
+                    model,
+                    inputTokens: (delta.input_tokens ?? 0) - (delta.cached_input_tokens ?? 0),
+                    outputTokens: delta.output_tokens ?? 0,
+                    cacheReadTokens: delta.cached_input_tokens ?? 0,
+                    cacheCreationTokens: 0,
+                    thinkingTokens: delta.reasoning_output_tokens ?? 0,
+                    tools: pendingTools,
+                    commands: pendingCommands,
+                    hasThinking: (delta.reasoning_output_tokens ?? 0) > 0,
+                    isError: false,
+                };
+                ev.activity = classify(ev);
+                events.push(ev);
+                pendingTools = [];
+                pendingCommands = [];
+            }
+        }
+    }
+    return {
+        events,
+        result: {
+            source: 'codex',
+            filesScanned,
+            eventsFound: events.length,
+            eventsInserted: 0,
+            note: filesScanned > 0 ? 'codex adapter is experimental — verify totals against `codex` usage screens' : undefined,
+        },
+    };
+}