tokaholics 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mathias Karlsson
+
+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,90 @@
+# tokaholics CLI
+
+Measures your **Claude Code** token burn and pushes it to the Tokaholics
+leaderboard. It reads **only usage numbers** (token counts, model, timestamp)
+from `~/.claude/projects/**/*.jsonl` — never your prompts, code, file names, or
+project names.
+
+The CLI is MIT-licensed and open source — read it before you run it.
+
+## What it touches on your machine
+
+`setup` is explicit about everything it does and asks before changing anything:
+
+| Action | Default | Notes |
+|--------|:-------:|-------|
+| Read `~/.claude/projects/**/*.jsonl` | ✅ | usage fields only — see [Privacy](#privacy) |
+| Upload daily `(day, model)` token totals | ✅ | via the `ingest` endpoint |
+| Store a device token | ✅ | macOS **Keychain**, never plaintext on disk |
+| Background sync agent (launchd, every 5 min) | ✅ | opt out with `--no-agent` |
+| Claude Code **Stop hook** in `~/.claude/settings.json` | ❌ | opt in with `--hook` |
+
+Nothing is installed silently, and everything is reversible (see
+[Uninstall](#uninstall)).
+
+## Get started
+
+```bash
+npx tokaholics setup <code>            # code from the iOS app: You → Connect a computer
+npx tokaholics setup <code> --hook     # …and also sync instantly after each session
+```
+
+`setup` pairs this Mac, backfills your history, and turns on background sync.
+It prints exactly what it will do and waits for your confirmation. That's it —
+open the app.
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `tokaholics setup <code> [--hook] [--no-agent] [-y]` | Pair + backfill + background sync (the one-liner above) |
+| `tokaholics login <code>` | Pair only (no sync/agent/hook) |
+| `tokaholics stats` | Show your local 7-day burn (**no upload**) |
+| `tokaholics projects` | Burn by project, last 30 days (**local only**) |
+| `tokaholics sync [--full]` | Parse new log lines and push changed days |
+| `tokaholics start [--interval 300]` | Install background sync (launchd, macOS) |
+| `tokaholics stop` | Remove background sync |
+| `tokaholics install-hook` / `uninstall-hook` | Add / remove the instant Stop hook |
+| `tokaholics status` | Show pairing/config |
+| `tokaholics logout` | Unpair this machine + remove the background agent |
+
+Try it with **no account** first — `npx tokaholics stats` runs fully offline.
+
+## Uninstall
+
+```bash
+tokaholics uninstall-hook   # if you added --hook
+tokaholics logout           # unpairs + removes the launchd agent
+```
+
+That removes the launchd agent, the Stop hook, and the Keychain token. The
+config dir `~/.tokaholics` can then be deleted.
+
+## How it works
+
+1. Streams every `.jsonl` session log line-by-line (memory-safe).
+2. Keeps only assistant `usage` rows, **deduped by `message.id`** (the same id
+   repeats across streaming rows).
+3. Aggregates **absolute** totals per `(day, model)` → idempotent upserts, so
+   re-running `sync` never double-counts.
+4. Pushes via a per-device token (only its SHA-256 hash is stored server-side).
+   Row-Level Security limits you to your own rows; others' numbers are only ever
+   visible as aggregates. Cost (USD) is computed server-side from a pricing table.
+
+The client holds no secret keys — only the public `publishable` key, which is
+safe to embed.
+
+## Privacy
+
+The only fields ever read from your logs are:
+`message.id`, `message.model`, `timestamp`, and the four `usage` token counts.
+No prompt text, file contents, file names, or project names leave your machine.
+
+## Dev (from the repo)
+
+```bash
+cd cli
+npm install
+node bin/tokaholics.js stats     # works offline, no account needed
+npm test                         # RPC smoke test (needs Supabase env vars)
+```

package/bin/tokaholics.js

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+// tokaholics — CLI that measures your Claude Code token burn and pushes it to
+// the leaderboard. Reads ONLY usage numbers from your logs, never your code.
+
+import { Command } from 'commander';
+import { hostname, platform } from 'node:os';
+import { createInterface } from 'node:readline';
+import { readFileSync } from 'node:fs';
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+import { aggregateUsage, aggregateByProject, daysAgo, today } from '../src/parse.js';
+import { readConfig, writeConfig, setSecret, clearSecret } from '../src/store.js';
+import { redeemPairing, pushUsage } from '../src/api.js';
+import { installAgent, uninstallAgent } from '../src/daemon.js';
+import { installHook, uninstallHook } from '../src/hook.js';
+import { aggregateIncremental, resetIncremental } from '../src/incremental.js';
+
+const program = new Command();
+program
+  .name('tokaholics')
+  .description('Track your Claude Code burn. Climb the leaderboard with your friends.')
+  .version(pkg.version);
+
+const fmt = (n) => (n / 1e6).toFixed(1) + 'M';
+const REPO = 'https://github.com/dragon6sic6/tokaholics-cli';
+
+// Yes/no prompt. Non-interactive (no TTY) resolves to the default so piped/CI
+// runs never hang. Enter accepts the default.
+function confirm(question, def = true) {
+  if (!process.stdin.isTTY) return Promise.resolve(def);
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const hint = def ? '[Y/n]' : '[y/N]';
+  return new Promise((resolve) => {
+    rl.question(`${question} ${hint} `, (a) => {
+      rl.close();
+      const s = a.trim().toLowerCase();
+      resolve(s === '' ? def : (s === 'y' || s === 'yes'));
+    });
+  });
+}
+
+// ── login / pairing ──────────────────────────────────────────────────────────
+program
+  .command('login')
+  .description('Pair this machine with your Tokaholics account')
+  .argument('<code>', '6-digit pairing code shown in the iOS app')
+  .option('--url <url>', 'Supabase project URL (first-time setup)')
+  .option('--anon <key>', 'Supabase anon key (first-time setup)')
+  .action(async (code, opts) => {
+    if (opts.url || opts.anon) {
+      await writeConfig({
+        ...(opts.url ? { supabaseUrl: opts.url } : {}),
+        ...(opts.anon ? { supabaseAnon: opts.anon } : {}),
+      });
+    }
+    const name = hostname();
+    const { device_id, device_token, user_id, username } = await redeemPairing(code, name, platform());
+    await setSecret(device_token);
+    await writeConfig({ deviceId: device_id, userId: user_id, username });
+    console.log(`✓ Paired as @${username} (device: ${name}).`);
+    console.log('  Run `tokaholics start` to sync in the background, or `tokaholics sync` once.');
+  });
+
+program
+  .command('setup')
+  .description('Pair + backfill + background sync. Add --hook for instant post-session sync.')
+  .argument('<code>', 'pairing code from the iOS app (You → Connect a computer)')
+  .option('--url <url>', 'Supabase project URL (first-time setup only)')
+  .option('--anon <key>', 'Supabase anon key (first-time setup only)')
+  .option('--hook', 'Also add a Claude Code Stop hook for instant sync (edits ~/.claude/settings.json)')
+  .option('--no-agent', 'Skip the background sync agent')
+  .option('-y, --yes', 'Skip the confirmation prompt (for non-interactive use)')
+  .action(async (code, opts) => {
+    if (opts.url || opts.anon) {
+      await writeConfig({
+        ...(opts.url ? { supabaseUrl: opts.url } : {}),
+        ...(opts.anon ? { supabaseAnon: opts.anon } : {}),
+      });
+    }
+
+    const wantAgent = opts.agent !== false;   // commander sets agent=false on --no-agent
+    const wantHook = !!opts.hook;
+
+    // Transparency: say exactly what we read and what we'll change, then consent.
+    console.log('');
+    console.log('Tokaholics measures token COUNTS only. It reads ~/.claude logs for usage');
+    console.log('numbers (tokens, model, timestamp) and never your prompts, code, file');
+    console.log(`names, or project names. Source: ${REPO}`);
+    console.log('');
+    console.log('This will:');
+    console.log('  • pair this Mac with your account (device token → macOS Keychain)');
+    console.log('  • read ~/.claude/projects/**/*.jsonl and upload daily token totals');
+    if (wantAgent) console.log('  • install a background sync agent (launchd, every 5 min)');
+    if (wantHook)  console.log('  • add a Stop hook to ~/.claude/settings.json (instant sync)');
+    if (!wantHook) console.log('  (no Claude-hook — add later with --hook or `tokaholics install-hook`)');
+    console.log('');
+    console.log(`Undo anytime:  tokaholics logout${wantHook ? '  +  tokaholics uninstall-hook' : ''}`);
+    console.log('');
+
+    if (!opts.yes && !(await confirm('Continue?', true))) {
+      console.log('Aborted — nothing was changed.');
+      return;
+    }
+
+    const name = hostname();
+    const { device_id, device_token, user_id, username } = await redeemPairing(code, name, platform());
+    await setSecret(device_token);
+    await writeConfig({ deviceId: device_id, userId: user_id, username });
+    console.log(`✓ Paired as @${username} (${name}).`);
+
+    await resetIncremental();
+    const { rows, changedDays } = await aggregateIncremental();
+    if (rows.length) {
+      const n = await pushUsage(rows);
+      const tot = rows.reduce((s, r) =>
+        s + r.input_tokens + r.output_tokens + r.cache_write_tokens + r.cache_read_tokens, 0);
+      console.log(`✓ Backfilled ${n} day/model rows (${fmt(tot)} tokens) across ${changedDays} days.`);
+    }
+
+    if (wantAgent) {
+      await installAgent({ intervalSec: 300 });
+      console.log('✓ Background sync running (every 5 min).');
+    } else {
+      console.log('• Background agent skipped — run `tokaholics start` later, or `tokaholics sync` by hand.');
+    }
+
+    if (wantHook) {
+      await installHook();
+      console.log('✓ Instant sync after every Claude Code session.');
+    } else {
+      console.log('• Instant Claude-hook not installed — run `tokaholics install-hook` if you want it.');
+    }
+
+    console.log('\n🔥 You are live on Tokaholics. Open the app and watch your burn.');
+  });
+
+program
+  .command('logout')
+  .description('Unpair this machine and remove everything (agent + hook)')
+  .action(async () => {
+    await clearSecret();
+    await writeConfig({ deviceId: null, userId: null });
+    await uninstallAgent();
+    await uninstallHook();
+    console.log('✓ Logged out. Background sync, the Claude hook, and the device token are all removed.');
+  });
+
+// ── sync ──────────────────────────────────────────────────────────────────────
+program
+  .command('sync')
+  .description('Incrementally parse new log lines and push changed days')
+  .option('--full', 'Rebuild from a full scan of all history')
+  .action(async (opts) => {
+    const cfg = await readConfig();
+    if (!cfg.deviceId) {
+      console.error('Not paired. Run `tokaholics login <code>` first.');
+      process.exit(1);
+    }
+    if (opts.full) await resetIncremental();
+    const { rows, changedDays, seeded } = await aggregateIncremental();
+    if (rows.length === 0) {
+      console.log('Up to date — nothing new to push.');
+      return;
+    }
+    const n = await pushUsage(rows);
+    console.log(`✓ Pushed ${n} day/model rows (${changedDays} day(s) changed${seeded ? ', full backfill' : ''}).`);
+  });
+
+// ── local stats (no network) ───────────────────────────────────────────────────
+program
+  .command('stats')
+  .description('Show your local burn for the last 7 days (no upload)')
+  .action(async () => {
+    const { rows } = await aggregateUsage({ sinceDay: daysAgo(7) });
+    const byDay = {};
+    for (const r of rows) {
+      const t = r.input_tokens + r.output_tokens + r.cache_write_tokens + r.cache_read_tokens;
+      byDay[r.day] = (byDay[r.day] || 0) + t;
+    }
+    console.log('Your burn (last 7 days):');
+    for (const [d, t] of Object.entries(byDay).sort()) {
+      const bar = '█'.repeat(Math.min(40, Math.round(t / 1e7)));
+      const tag = d === today() ? '  ← today' : '';
+      console.log(`  ${d}  ${fmt(t).padStart(7)}  ${bar}${tag}`);
+    }
+  });
+
+program
+  .command('projects')
+  .description('Show your burn broken down by project (last 30 days, local)')
+  .action(async () => {
+    const rows = await aggregateByProject({ sinceDay: daysAgo(30) });
+    if (rows.length === 0) { console.log('No usage found.'); return; }
+    const max = rows[0].tokens;
+    console.log('Your burn by project (last 30 days):');
+    for (const r of rows.slice(0, 20)) {
+      const bar = '█'.repeat(Math.max(1, Math.round((r.tokens / max) * 30)));
+      console.log(`  ${fmt(r.tokens).padStart(7)}  ${bar}  ${r.project}`);
+    }
+  });
+
+// ── background agent ────────────────────────────────────────────────────────────
+program
+  .command('start')
+  .description('Install the background sync agent (launchd, every 5 min)')
+  .option('--interval <sec>', 'Sync interval in seconds', '300')
+  .action(async (opts) => {
+    const plist = await installAgent({ intervalSec: parseInt(opts.interval, 10) });
+    console.log(`✓ Background sync running. (${plist})`);
+  });
+
+program
+  .command('stop')
+  .description('Remove the background sync agent')
+  .action(async () => {
+    await uninstallAgent();
+    console.log('✓ Background sync stopped.');
+  });
+
+program
+  .command('install-hook')
+  .description('Push usage instantly after every Claude Code session (Stop hook)')
+  .action(async () => {
+    const path = await installHook();
+    console.log(`✓ Realtime hook installed in ${path}.`);
+    console.log('  Your burn now syncs the moment each Claude Code session ends.');
+  });
+
+program
+  .command('uninstall-hook')
+  .description('Remove the Claude Code Stop hook')
+  .action(async () => {
+    await uninstallHook();
+    console.log('✓ Realtime hook removed.');
+  });
+
+program
+  .command('status')
+  .description('Show pairing + config status')
+  .action(async () => {
+    const cfg = await readConfig();
+    console.log('Account:   ', cfg.username ? `@${cfg.username}` : '(not paired)');
+    console.log('Device id: ', cfg.deviceId || '—');
+    console.log('Supabase:  ', cfg.supabaseUrl || '(default/env)');
+  });
+
+program.parseAsync().catch((e) => {
+  console.error(`✗ ${e?.message || e}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "tokaholics",
+  "version": "0.2.0",
+  "description": "Track your Claude Code token burn and climb the leaderboard with your friends. Reads usage counts only — never your prompts or code.",
+  "type": "module",
+  "bin": {
+    "tokaholics": "bin/tokaholics.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "tokens",
+    "usage",
+    "leaderboard",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@supabase/supabase-js": "^2.45.0"
+  },
+  "scripts": {
+    "start": "node bin/tokaholics.js",
+    "test": "node tests/rpc-smoke.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dragon6sic6/tokaholics-cli.git"
+  },
+  "homepage": "https://tokaholics.pro",
+  "bugs": {
+    "url": "https://github.com/dragon6sic6/tokaholics-cli/issues"
+  },
+  "author": "Mathias Karlsson",
+  "license": "MIT"
+}

package/src/api.js

@@ -0,0 +1,65 @@
+// Supabase access for the CLI. The CLI authenticates with a per-device token
+// (issued by `redeem-pairing-code`) and writes ONLY through the `ingest` edge
+// function. It never touches the database directly and holds no service key.
+
+import { readConfig, getSecret } from './store.js';
+
+// Built-in defaults so a freshly-installed CLI knows where to talk.
+// The publishable key is safe to embed in clients. Overridable via config/env.
+const DEFAULT_URL =
+  process.env.TOKAHOLICS_SUPABASE_URL || 'https://pdfuopfqhubsumcpfqdb.supabase.co';
+const DEFAULT_ANON =
+  process.env.TOKAHOLICS_SUPABASE_ANON || 'sb_publishable__Z3ntgU8fQGyA7s8VJlo5g_JcAjItQe';
+
+async function endpoint() {
+  const cfg = await readConfig();
+  const url = cfg.supabaseUrl || DEFAULT_URL;
+  const anon = cfg.supabaseAnon || DEFAULT_ANON;
+  if (!url || !anon) throw new Error('Missing Supabase config (url/anon).');
+  return { url, anon };
+}
+
+async function callFn(name, body) {
+  const { url, anon } = await endpoint();
+  const res = await fetch(`${url}/functions/v1/${name}`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      apikey: anon,
+      Authorization: `Bearer ${anon}`,
+    },
+    body: JSON.stringify(body),
+  });
+  const text = await res.text();
+  let data;
+  try { data = JSON.parse(text); } catch { data = { raw: text }; }
+  if (!res.ok) throw new Error(`${name} failed (${res.status}): ${data.error || text}`);
+  return data;
+}
+
+// Redeem a 6-digit pairing code from the iOS app.
+// Returns { device_id, user_id, username, device_token }.
+export async function redeemPairing(code, deviceName, plat) {
+  return callFn('redeem-pairing-code', {
+    code,
+    device_name: deviceName,
+    platform: plat,
+  });
+}
+
+// Idempotent upsert of absolute daily aggregates via the ingest function.
+export async function pushUsage(rows) {
+  const token = await getSecret();
+  if (!token) throw new Error('No device token. Run `tokaholics login <code>` first.');
+  const payload = rows.map((r) => ({
+    day: r.day,
+    model: r.model,
+    input_tokens: r.input_tokens,
+    output_tokens: r.output_tokens,
+    cache_write_tokens: r.cache_write_tokens,
+    cache_read_tokens: r.cache_read_tokens,
+    message_count: r.message_count,
+  }));
+  const out = await callFn('ingest', { device_token: token, rows: payload });
+  return out.rows;
+}

package/src/daemon.js

@@ -0,0 +1,55 @@
+// Installs the CLI as a macOS launchd agent so usage syncs in the background
+// even after reboot. Runs `tokaholics sync` on an interval.
+
+import { writeFile, mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir, platform } from 'node:os';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+
+const pexec = promisify(execFile);
+const LABEL = 'ai.tokaholics.sync';
+const PLIST = join(homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
+
+function binPath() {
+  // Absolute path to bin/tokaholics.js inside this package.
+  return fileURLToPath(new URL('../bin/tokaholics.js', import.meta.url));
+}
+
+export async function installAgent({ intervalSec = 300 } = {}) {
+  if (platform() !== 'darwin') {
+    throw new Error('Background agent is macOS-only for now. Use `tokaholics sync` via cron on Linux.');
+  }
+  await mkdir(join(homedir(), 'Library', 'LaunchAgents'), { recursive: true });
+  const node = process.execPath;
+  const logDir = join(homedir(), '.tokaholics');
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${node}</string>
+    <string>${binPath()}</string>
+    <string>sync</string>
+  </array>
+  <key>StartInterval</key><integer>${intervalSec}</integer>
+  <key>RunAtLoad</key><true/>
+  <key>StandardOutPath</key><string>${join(logDir, 'sync.log')}</string>
+  <key>StandardErrorPath</key><string>${join(logDir, 'sync.err.log')}</string>
+</dict>
+</plist>`;
+  await writeFile(PLIST, plist);
+  // Reload if already loaded.
+  try { await pexec('launchctl', ['unload', PLIST]); } catch { /* not loaded */ }
+  await pexec('launchctl', ['load', PLIST]);
+  return PLIST;
+}
+
+export async function uninstallAgent() {
+  if (platform() !== 'darwin') return;
+  try { await pexec('launchctl', ['unload', PLIST]); } catch { /* */ }
+  try { await rm(PLIST); } catch { /* */ }
+}

package/src/hook.js

@@ -0,0 +1,63 @@
+// Installs a Claude Code "Stop" hook so usage is pushed immediately after every
+// session ends — making friends' leaderboards update in near real-time.
+//
+// We edit ~/.claude/settings.json idempotently and tag our entry so it can be
+// cleanly removed again. Existing hooks/settings are preserved.
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const SETTINGS = join(homedir(), '.claude', 'settings.json');
+const TAG = 'tokaholics'; // identifies our hook entry
+
+function syncCommand() {
+  const bin = fileURLToPath(new URL('../bin/tokaholics.js', import.meta.url));
+  // Quote the path in case it contains spaces.
+  return `"${process.execPath}" "${bin}" sync`;
+}
+
+async function readSettings() {
+  try {
+    return JSON.parse(await readFile(SETTINGS, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+async function writeSettings(obj) {
+  await mkdir(join(homedir(), '.claude'), { recursive: true });
+  await writeFile(SETTINGS, JSON.stringify(obj, null, 2));
+}
+
+function withoutOurHook(stopArray) {
+  // Remove any Stop entries whose commands reference tokaholics.
+  return (stopArray || []).filter((entry) => {
+    const cmds = (entry.hooks || []).map((h) => h.command || '');
+    return !cmds.some((c) => c.includes(TAG));
+  });
+}
+
+export async function installHook() {
+  const s = await readSettings();
+  s.hooks = s.hooks || {};
+  s.hooks.Stop = withoutOurHook(s.hooks.Stop); // de-dupe first
+  s.hooks.Stop.push({
+    matcher: '',
+    hooks: [{ type: 'command', command: syncCommand() }],
+  });
+  await writeSettings(s);
+  return SETTINGS;
+}
+
+export async function uninstallHook() {
+  const s = await readSettings();
+  if (s.hooks?.Stop) {
+    s.hooks.Stop = withoutOurHook(s.hooks.Stop);
+    if (s.hooks.Stop.length === 0) delete s.hooks.Stop;
+    if (Object.keys(s.hooks).length === 0) delete s.hooks;
+  }
+  await writeSettings(s);
+  return SETTINGS;
+}

package/src/incremental.js

@@ -0,0 +1,146 @@
+// Incremental sync: instead of re-scanning every .jsonl on each run, we remember
+// a byte offset per file and only read the bytes appended since last time, keeping
+// running absolute per-(day,model) totals AND a persisted set of every seen
+// message.id in a local state file. The ingest API is idempotent (absolute
+// upsert), so we push only the days that actually changed.
+//
+// The seen-id set MUST be global + persisted: the same message.id can appear in
+// multiple files (resumed/branched sessions) and across a sync boundary (streaming
+// duplicates straddling an offset), and double-counting is permanent under an
+// absolute upsert. Deduping against one cross-run set fixes both.
+//
+// State: ~/.tokaholics/sync-state.json
+//   { offsets: {"<path>": <bytes>}, totals: {"<day>\t<model>": {...}}, seen: ["<id>", ...] }
+
+import { open, readdir, stat, readFile, writeFile, rename, mkdir } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createInterface } from 'node:readline';
+
+const DIR = join(homedir(), '.tokaholics');
+const STATE = join(DIR, 'sync-state.json');
+const PROJECTS_DIR = join(homedir(), '.claude', 'projects');
+
+function localDay(iso) {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return null;
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  return `${y}-${m}-${day}`;
+}
+
+async function* walkJsonl(dir) {
+  let entries;
+  try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) yield* walkJsonl(full);
+    else if (e.isFile() && e.name.endsWith('.jsonl')) yield full;
+  }
+}
+
+async function loadState() {
+  try { return JSON.parse(await readFile(STATE, 'utf8')); } catch { return null; }
+}
+async function saveState({ offsets, totals, seen }) {
+  await mkdir(DIR, { recursive: true });
+  const tmp = STATE + '.tmp';
+  await writeFile(tmp, JSON.stringify({ offsets, totals, seen: [...seen] }));
+  await rename(tmp, STATE);   // atomic: never leave a half-written state file
+}
+
+function emptyTotal(day, model) {
+  return { day, model, input_tokens: 0, output_tokens: 0,
+           cache_write_tokens: 0, cache_read_tokens: 0, message_count: 0 };
+}
+function addUsage(t, usage) {
+  t.input_tokens       += usage.input_tokens || 0;
+  t.output_tokens      += usage.output_tokens || 0;
+  t.cache_write_tokens += usage.cache_creation_input_tokens || 0;
+  t.cache_read_tokens  += usage.cache_read_input_tokens || 0;
+  t.message_count      += 1;
+}
+function rowsFor(totals, days) {
+  const out = [];
+  for (const t of Object.values(totals)) {
+    if (!days || days.has(t.day)) out.push(t);
+  }
+  return out;
+}
+
+// Apply one assistant-usage line to totals + seen (global dedupe). Returns the
+// day it touched, or null.
+function applyLine(line, totals, seen) {
+  if (!line || line[0] !== '{') return null;
+  let obj; try { obj = JSON.parse(line); } catch { return null; }
+  const msg = obj.message; const usage = msg?.usage;
+  if (!usage || !msg?.id || seen.has(msg.id)) return null;
+  seen.add(msg.id);
+  const day = localDay(obj.timestamp); if (!day) return null;
+  const key = `${day}\t${msg.model || 'unknown'}`;
+  if (!totals[key]) totals[key] = emptyTotal(day, msg.model || 'unknown');
+  addUsage(totals[key], usage);
+  return day;
+}
+
+// First-run seed: a full streaming scan that records totals + the global seen set
+// + per-file offsets (so subsequent runs only read appended bytes).
+async function seed() {
+  const totals = {}; const seen = new Set(); const offsets = {};
+  for await (const file of walkJsonl(PROJECTS_DIR)) {
+    const rl = createInterface({
+      input: createReadStream(file, { encoding: 'utf8' }), crlfDelay: Infinity });
+    for await (const line of rl) applyLine(line, totals, seen);
+    offsets[file] = (await stat(file)).size;
+  }
+  await saveState({ offsets, totals, seen });
+  return { rows: rowsFor(totals, null), changedDays: new Set(Object.values(totals).map((t) => t.day)).size, seeded: true };
+}
+
+/**
+ * @returns {Promise<{rows: Array, changedDays: number, seeded: boolean}>}
+ *   rows = absolute totals for days that changed this run (ready to upsert).
+ */
+export async function aggregateIncremental() {
+  const state = await loadState();
+  if (!state || !state.totals || !Array.isArray(state.seen)) return seed();
+
+  const { offsets, totals } = state;
+  const seen = new Set(state.seen);
+  const changed = new Set();
+
+  for await (const file of walkJsonl(PROJECTS_DIR)) {
+    const size = (await stat(file)).size;
+    let offset = offsets[file] || 0;
+    if (size < offset) offset = 0;          // file truncated/rotated → re-read
+    if (size <= offset) continue;           // nothing new
+
+    const fh = await open(file, 'r');
+    try {
+      const len = size - offset;
+      const buf = Buffer.alloc(len);
+      await fh.read(buf, 0, len, offset);
+      const text = buf.toString('utf8');
+      const lastNL = text.lastIndexOf('\n');
+      if (lastNL === -1) continue;          // no complete line yet
+      const complete = text.slice(0, lastNL + 1);
+      offsets[file] = offset + Buffer.byteLength(complete, 'utf8');
+      for (const line of complete.split('\n')) {
+        const day = applyLine(line, totals, seen);
+        if (day) changed.add(day);
+      }
+    } finally {
+      await fh.close();
+    }
+  }
+
+  await saveState({ offsets, totals, seen });
+  return { rows: rowsFor(totals, changed), changedDays: changed.size, seeded: false };
+}
+
+/** Drop incremental state so the next sync rebuilds from a full scan. */
+export async function resetIncremental() {
+  try { await writeFile(STATE, JSON.stringify({})); } catch { /* */ }
+}

package/src/store.js

@@ -0,0 +1,82 @@
+// Local config + secure secret storage.
+//   • Non-secret config (supabase url, anon key, device_id) → ~/.tokaholics/config.json
+//   • Secret device JWT → macOS Keychain via the `security` CLI (never on disk in plaintext).
+//     On non-macOS we fall back to a 0600 file (documented tradeoff).
+
+import { mkdir, readFile, writeFile, chmod } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir, platform } from 'node:os';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const pexec = promisify(execFile);
+const DIR = join(homedir(), '.tokaholics');
+const CONFIG = join(DIR, 'config.json');
+const KEYCHAIN_SERVICE = 'tokaholics-device-jwt';
+
+async function ensureDir() {
+  await mkdir(DIR, { recursive: true });
+}
+
+export async function readConfig() {
+  try {
+    return JSON.parse(await readFile(CONFIG, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export async function writeConfig(patch) {
+  await ensureDir();
+  const cur = await readConfig();
+  const next = { ...cur, ...patch };
+  await writeFile(CONFIG, JSON.stringify(next, null, 2));
+  await chmod(CONFIG, 0o600);
+  return next;
+}
+
+// ── secret (device JWT) ──────────────────────────────────────────────────────
+export async function setSecret(jwt) {
+  if (platform() === 'darwin') {
+    // -U updates if present. Stored in the login keychain, ACL'd to this tool.
+    await pexec('security', [
+      'add-generic-password', '-U',
+      '-s', KEYCHAIN_SERVICE,
+      '-a', 'default',
+      '-w', jwt,
+    ]);
+  } else {
+    await ensureDir();
+    const f = join(DIR, '.jwt');
+    await writeFile(f, jwt);
+    await chmod(f, 0o600);
+  }
+}
+
+export async function getSecret() {
+  if (platform() === 'darwin') {
+    try {
+      const { stdout } = await pexec('security', [
+        'find-generic-password', '-s', KEYCHAIN_SERVICE, '-a', 'default', '-w',
+      ]);
+      return stdout.trim();
+    } catch {
+      return null;
+    }
+  }
+  try {
+    return (await readFile(join(DIR, '.jwt'), 'utf8')).trim();
+  } catch {
+    return null;
+  }
+}
+
+export async function clearSecret() {
+  if (platform() === 'darwin') {
+    try {
+      await pexec('security', ['delete-generic-password', '-s', KEYCHAIN_SERVICE, '-a', 'default']);
+    } catch { /* not found */ }
+  }
+}
+
+export const paths = { DIR, CONFIG };