modelmeter-collect 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# modelmeter-collect
+
+Report LLM token usage to [ModelMeter](https://modelmeter.dev) from the session logs
+that **subscription** coding tools already write to your disk. No API key, no billing
+access. It sends only model names and token counts. **Never your prompts, never your keys.**
+
+- **Claude Code** — `~/.claude/projects/**/*.jsonl` (per-message `usage`)
+- **Codex** — `~/.codex/sessions/**/*.jsonl` (`token_count` events)
+
+It dedupes (state in `~/.modelmeter/collector-state.json`), so every run is safe to repeat.
+
+Not covered: the **ChatGPT** consumer app (no per-message token data exists) and **Cursor**
+on a Pro plan (usage stays on Cursor's servers).
+
+## Quick start
+
+```bash
+# 1. Grab an ingest token from the Providers tab at https://modelmeter.dev, then:
+npx modelmeter-collect init mm_live_xxxxxxxx
+
+# 2. Backfill the last couple of weeks:
+npx modelmeter-collect
+
+# Preview what would be sent, without sending:
+MODELMETER_DRYRUN=1 npx modelmeter-collect
+```
+
+`init` writes `~/.modelmeter/config.json` (chmod 600) with your token and the ingest URL.
+Prefer env vars? Set `MODELMETER_TOKEN` and `MODELMETER_INGEST_URL` and skip `init`.
+
+## Keep it live (per prompt)
+
+**Claude Code** — add a `Stop` hook (fires after every response). It passes the session
+transcript on stdin, so the collector reads just that one file:
+
+```json
+{ "hooks": { "Stop": [ { "hooks": [ { "type": "command",
+  "command": "npx -y modelmeter-collect" } ] } ] } }
+```
+
+**Codex** — its single `notify` slot is often already used, so the scheduled job below
+picks up Codex within ~a minute. If your `notify` is free:
+`notify = ["npx", "-y", "modelmeter-collect"]`.
+
+## Scheduled backstop (macOS launchd, every 60s)
+
+Catches Codex and anything a hook missed. Light scan (`MODELMETER_LOOKBACK_DAYS=1`); it
+no-ops when there is nothing new. Save as `~/Library/LaunchAgents/dev.modelmeter.collector.plist`
+and `launchctl load -w` it. Use an absolute `npx` path (`which npx`):
+
+```xml
+<?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>dev.modelmeter.collector</string>
+  <key>ProgramArguments</key>
+  <array><string>/opt/homebrew/bin/npx</string><string>-y</string><string>modelmeter-collect</string></array>
+  <key>EnvironmentVariables</key><dict><key>MODELMETER_LOOKBACK_DAYS</key><string>1</string></dict>
+  <key>StartInterval</key><integer>60</integer>
+  <key>RunAtLoad</key><true/>
+  <key>StandardErrorPath</key><string>/Users/you/.modelmeter/collector.log</string>
+</dict></plist>
+```
+
+(Linux: a 60s `systemd` timer or a `* * * * *` cron line calling `npx -y modelmeter-collect`
+does the same job.)
+
+## Configuration
+
+| Env var | Default | Meaning |
+| --- | --- | --- |
+| `MODELMETER_TOKEN` | from config file | Your `mm_live_...` ingest token |
+| `MODELMETER_INGEST_URL` | from config file | The ingest endpoint |
+| `MODELMETER_LOOKBACK_DAYS` | `14` | How many days of logs to scan |
+| `MODELMETER_DRYRUN` | unset | When set, print the payload instead of sending |
+
+Requires Node 18+ (built-in `fetch`). The token lives only in `~/.modelmeter/config.json`,
+never in the hook command or the plist.

package/cli.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// modelmeter-collect: configure and run the ModelMeter local usage collector.
+// Reports only model names + token counts from local Claude Code / Codex logs.
+// Never prompts, never keys.
+//
+//   npx modelmeter-collect init <mm_live_token>   # one-time: save the token
+//   npx modelmeter-collect                          # scan local logs and report
+//   MODELMETER_DRYRUN=1 npx modelmeter-collect      # preview without sending
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HOME = homedir()
+const MM_DIR = join(HOME, '.modelmeter')
+const CONFIG_PATH = join(MM_DIR, 'config.json')
+const DEFAULT_INGEST_URL = 'https://tqgmrixeadjkggybordj.supabase.co/functions/v1/ingest'
+
+const args = process.argv.slice(2)
+const cmd = args[0]
+
+function readConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+function writeConfig(cfg) {
+  if (!existsSync(MM_DIR)) mkdirSync(MM_DIR, { recursive: true })
+  writeFileSync(CONFIG_PATH, `${JSON.stringify(cfg, null, 2)}\n`)
+  try {
+    chmodSync(CONFIG_PATH, 0o600)
+  } catch {
+    // best effort: platforms without POSIX perms still get the file
+  }
+}
+
+function flag(name) {
+  const i = args.indexOf(name)
+  return i >= 0 ? args[i + 1] : undefined
+}
+
+function printHelp() {
+  console.log(`modelmeter-collect — report local LLM token usage to ModelMeter
+
+Usage:
+  npx modelmeter-collect init <token> [--url <ingest-url>]
+  npx modelmeter-collect                 scan local logs and report
+  npx modelmeter-collect --help
+
+Commands:
+  init    Save your ingest token to ~/.modelmeter/config.json (chmod 600).
+          Pass the token as an argument or via MODELMETER_TOKEN.
+  (none)  Scan Claude Code + Codex logs and report token counts. Deduped,
+          so it is safe to run repeatedly. MODELMETER_DRYRUN=1 previews only.
+
+It sends only model names and token counts. Never your prompts, never your keys.
+Get an ingest token from the Providers tab at https://modelmeter.dev`)
+}
+
+async function runCollector() {
+  // Delegate to the collector, which reads ~/.modelmeter/config.json or env.
+  const here = dirname(fileURLToPath(import.meta.url))
+  await import(join(here, 'collect.mjs'))
+}
+
+if (cmd === 'help' || args.includes('--help') || args.includes('-h')) {
+  printHelp()
+  process.exit(0)
+}
+
+if (cmd === 'init' || cmd === 'setup') {
+  const positional = args[1] && !args[1].startsWith('-') ? args[1] : undefined
+  const token = positional || process.env.MODELMETER_TOKEN
+  const url = flag('--url') || flag('--ingest-url') || readConfig().ingestUrl || DEFAULT_INGEST_URL
+  if (!token) {
+    console.error('No token provided. Run: npx modelmeter-collect init <mm_live_token>')
+    console.error('Get one from the Providers tab at https://modelmeter.dev')
+    process.exit(1)
+  }
+  if (!token.startsWith('mm_live_')) {
+    console.error('That does not look like a ModelMeter ingest token (expected mm_live_...).')
+    process.exit(1)
+  }
+  writeConfig({ token, ingestUrl: url })
+  console.log(`Saved ${CONFIG_PATH} (chmod 600).`)
+  console.log('')
+  console.log('Next:')
+  console.log('  1. Backfill now:   npx modelmeter-collect')
+  console.log('  2. Keep it live:   see the hook + scheduled-job snippets in the README.')
+  process.exit(0)
+}
+
+// Default: scan and report.
+await runCollector()

package/collect.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+// ModelMeter local usage collector for SUBSCRIPTION coding tools (no API key).
+// Reports token counts (never prompts/keys) from local logs to ModelMeter.
+//
+// Invocation modes (all safe to combine; dedup prevents double counting):
+//   - Claude Code Stop/SessionEnd hook: JSON on stdin with transcript_path -> that file only (fast)
+//   - Codex notify: JSON event as last argv -> newest Codex session only (fast)
+//   - scheduled / manual (no stdin, no arg): full 14-day scan of both tools
+//
+// Config: MODELMETER_TOKEN + MODELMETER_INGEST_URL from env, or ~/.modelmeter/config.json
+//   { "token": "mm_live_...", "ingestUrl": "https://<ref>.supabase.co/functions/v1/ingest" }
+import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const HOME = homedir()
+const MM_DIR = join(HOME, '.modelmeter')
+const STATE_PATH = join(MM_DIR, 'collector-state.json')
+const CONFIG_PATH = join(MM_DIR, 'config.json')
+const LOOKBACK_DAYS = Number(process.env.MODELMETER_LOOKBACK_DAYS) || 14
+
+let cfg = {}
+try {
+  cfg = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'))
+} catch {
+  cfg = {}
+}
+const TOKEN = process.env.MODELMETER_TOKEN || cfg.token
+const INGEST_URL = process.env.MODELMETER_INGEST_URL || cfg.ingestUrl
+if (!TOKEN || !INGEST_URL) process.exit(0) // not configured: do nothing, never block
+
+let state = { claude: {}, codex: {} }
+try {
+  state = { claude: {}, codex: {}, ...JSON.parse(readFileSync(STATE_PATH, 'utf8')) }
+} catch {
+  // first run
+}
+
+// --- invocation detection -------------------------------------------------
+let hookInput = null
+if (!process.stdin.isTTY) {
+  try {
+    const s = readFileSync(0, 'utf8')
+    if (s.trim()) hookInput = JSON.parse(s)
+  } catch {
+    hookInput = null
+  }
+}
+let codexNotify = null
+const lastArg = process.argv[process.argv.length - 1]
+if (lastArg && lastArg.trim().startsWith('{')) {
+  try {
+    codexNotify = JSON.parse(lastArg)
+  } catch {
+    codexNotify = null
+  }
+}
+
+// --- file discovery -------------------------------------------------------
+const cutoff = Date.now() - LOOKBACK_DAYS * 86_400_000
+function* walk(dir) {
+  let entries = []
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return
+  }
+  for (const e of entries) {
+    const p = join(dir, e.name)
+    if (e.isDirectory()) yield* walk(p)
+    else if (e.isFile() && p.endsWith('.jsonl')) yield p
+  }
+}
+function recentFiles(dir, limit = Infinity) {
+  const out = []
+  for (const p of walk(dir)) {
+    try {
+      const m = statSync(p).mtimeMs
+      if (m >= cutoff) out.push([m, p])
+    } catch {
+      // ignore
+    }
+  }
+  out.sort((a, b) => b[0] - a[0])
+  return out.slice(0, limit).map(([, p]) => p)
+}
+
+const events = []
+
+// --- Claude Code: assistant turns carry message.usage; dedup by message uuid.
+function scanClaude(files) {
+  for (const file of files) {
+    let text = ''
+    try {
+      text = readFileSync(file, 'utf8')
+    } catch {
+      continue
+    }
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue
+      let o
+      try {
+        o = JSON.parse(line)
+      } catch {
+        continue
+      }
+      const msg = o.message
+      if (!msg || msg.role !== 'assistant' || !msg.usage) continue
+      const id = o.uuid || `${o.timestamp ?? ''}:${msg.id ?? ''}`
+      if (!id || state.claude[id]) continue
+      state.claude[id] = 1
+      const u = msg.usage
+      events.push({
+        provider: 'anthropic',
+        model: msg.model || 'claude-unknown',
+        occurredOn: (o.timestamp || '').slice(0, 10) || undefined,
+        uncachedInputTokens: u.input_tokens || 0,
+        cacheReadInputTokens: u.cache_read_input_tokens || 0,
+        cacheCreationInputTokens: u.cache_creation_input_tokens || 0,
+        outputTokens: u.output_tokens || 0,
+        numRequests: 1,
+      })
+    }
+  }
+}
+
+// --- Codex: cumulative token_count events; report per-session delta.
+function findLastTokenCount(obj) {
+  let last = null
+  const stack = [obj]
+  while (stack.length) {
+    const d = stack.pop()
+    if (Array.isArray(d)) stack.push(...d)
+    else if (d && typeof d === 'object') {
+      if (d.type === 'token_count' && d.info?.total_token_usage) last = d.info.total_token_usage
+      for (const v of Object.values(d)) stack.push(v)
+    }
+  }
+  return last
+}
+function scanCodex(files) {
+  for (const file of files) {
+    const m = file.match(/rollout-(\d{4}-\d{2}-\d{2})T[\d-]+-([0-9a-f-]+)\.jsonl$/)
+    if (!m) continue
+    const date = m[1]
+    const sessionId = m[2]
+    let totals = null
+    let model = 'gpt-5'
+    let text = ''
+    try {
+      text = readFileSync(file, 'utf8')
+    } catch {
+      continue
+    }
+    for (const line of text.split('\n')) {
+      if (!line.trim()) continue
+      let o
+      try {
+        o = JSON.parse(line)
+      } catch {
+        continue
+      }
+      const t = findLastTokenCount(o)
+      if (t) totals = t
+      if (typeof o.model === 'string') model = o.model
+      else if (typeof o.payload?.model === 'string') model = o.payload.model
+    }
+    if (!totals) continue
+    const prev = state.codex[sessionId] || {
+      input_tokens: 0,
+      cached_input_tokens: 0,
+      output_tokens: 0,
+      reasoning_output_tokens: 0,
+    }
+    const dInput = Math.max(0, (totals.input_tokens || 0) - prev.input_tokens)
+    const dCached = Math.max(0, (totals.cached_input_tokens || 0) - prev.cached_input_tokens)
+    const dOut = Math.max(0, (totals.output_tokens || 0) - prev.output_tokens)
+    const dReason = Math.max(0, (totals.reasoning_output_tokens || 0) - prev.reasoning_output_tokens)
+    if (dInput + dCached + dOut + dReason > 0) {
+      events.push({
+        provider: 'openai',
+        model,
+        occurredOn: date,
+        uncachedInputTokens: Math.max(0, dInput - dCached),
+        cacheReadInputTokens: dCached,
+        cacheCreationInputTokens: 0,
+        outputTokens: dOut + dReason, // reasoning tokens bill as output
+        numRequests: 1,
+      })
+      state.codex[sessionId] = totals
+    }
+  }
+}
+
+if (hookInput?.transcript_path) {
+  scanClaude([hookInput.transcript_path]) // Claude Code hook: just this session
+} else if (codexNotify) {
+  scanCodex(recentFiles(join(HOME, '.codex', 'sessions'), 2)) // Codex notify: newest session(s)
+} else {
+  scanClaude(recentFiles(join(HOME, '.claude', 'projects')))
+  scanCodex(recentFiles(join(HOME, '.codex', 'sessions')))
+}
+
+// Collapse to one row per (provider, model, day) so the request stays small.
+const byKey = new Map()
+for (const e of events) {
+  const date = e.occurredOn || new Date().toISOString().slice(0, 10)
+  const key = `${e.provider}|${e.model}|${date}`
+  const cur = byKey.get(key) || {
+    provider: e.provider,
+    model: e.model,
+    occurredOn: date,
+    uncachedInputTokens: 0,
+    cacheReadInputTokens: 0,
+    cacheCreationInputTokens: 0,
+    outputTokens: 0,
+    numRequests: 0,
+  }
+  cur.uncachedInputTokens += e.uncachedInputTokens || 0
+  cur.cacheReadInputTokens += e.cacheReadInputTokens || 0
+  cur.cacheCreationInputTokens += e.cacheCreationInputTokens || 0
+  cur.outputTokens += e.outputTokens || 0
+  cur.numRequests += e.numRequests || 1
+  byKey.set(key, cur)
+}
+const payload = [...byKey.values()]
+
+if (payload.length === 0) {
+  process.exit(0)
+}
+
+if (process.env.MODELMETER_DRYRUN) {
+  const tally = {}
+  for (const e of events) tally[e.provider] = (tally[e.provider] || 0) + 1
+  console.log(`DRY RUN: ${events.length} raw events -> ${payload.length} daily rows`, tally)
+  console.log(JSON.stringify(payload, null, 2))
+  process.exit(0)
+}
+
+try {
+  const res = await fetch(INGEST_URL, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ source: 'collector', events: payload }),
+  })
+  if (res.ok) {
+    if (!existsSync(MM_DIR)) mkdirSync(MM_DIR, { recursive: true })
+    writeFileSync(STATE_PATH, JSON.stringify(state))
+    console.error(`modelmeter: reported ${payload.length} usage rows`)
+  } else {
+    console.error(`modelmeter: ingest returned ${res.status}`)
+  }
+} catch (err) {
+  console.error(`modelmeter: ${err.message}`)
+}
+process.exit(0)

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "modelmeter-collect",
+  "version": "0.1.0",
+  "description": "Report LLM token usage from local Claude Code / Codex logs to ModelMeter. Token counts only, never prompts or keys.",
+  "type": "module",
+  "bin": {
+    "modelmeter-collect": "cli.mjs"
+  },
+  "files": [
+    "cli.mjs",
+    "collect.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "keywords": [
+    "llm",
+    "tokens",
+    "token-usage",
+    "claude-code",
+    "codex",
+    "modelmeter"
+  ],
+  "homepage": "https://modelmeter.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/newtorob/modelmeter.git",
+    "directory": "tools/modelmeter-collect"
+  }
+}