modelmeter-collect 0.9.0 → 0.10.0

package/README.md

@@ -12,13 +12,23 @@ It dedupes (state in `~/.modelmeter/collector-state.json`), so every run is safe
 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
+## Try it, no account
+
+```bash
+# See where your Claude Code / Codex tokens go - signals + tips, runs locally:
+npx modelmeter-collect
+```
+
+With no token configured this reads your local logs and prints your cache reuse, top MCP
+server, context-bloat, and recommendations. Nothing is sent.
+
+## Track it over time
 
 ```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:
+# 2. Backfill the last couple of weeks (now that a token is saved, it reports usage):
 npx modelmeter-collect
 
 # Preview what would be sent, without sending:

package/cli.mjs

@@ -23,6 +23,7 @@ import {
   claudeSessionSummary,
   codexSessionSummary,
   buildLocalRecommendations,
+  summarizeSignals,
 } from './lib.mjs'
 
 const HOME = homedir()
@@ -72,8 +73,9 @@ Commands:
           status, and exactly what would be sent. Add --recommendations for
           local optimization tips (cache, MCP, output, context bloat), or
           --payload for the raw JSON (token counts only, never transcript text).
-  (none)  Scan Claude Code + Codex logs and report token counts. Deduped,
-          so it is safe to run repeatedly. MODELMETER_DRYRUN=1 previews only.
+  (none)  No token yet? Shows your local optimization signals + tips from
+          Claude Code / Codex logs, no account needed. With a token saved,
+          it scans and reports usage (deduped, safe to run repeatedly).
 
 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`)
@@ -185,7 +187,7 @@ function recentSessionFiles(dir, cutoffMs, limit) {
     .map((x) => x.p)
 }
 
-function printRecommendations(cutoffMs) {
+function readSummaries(cutoffMs) {
   const summaries = []
   const sources = [
     [join(HOME, '.claude', 'projects'), claudeSessionSummary],
@@ -203,6 +205,27 @@ function printRecommendations(cutoffMs) {
       if (summary) summaries.push(summary)
     }
   }
+  return summaries
+}
+
+function pct(x) {
+  return `${Math.round(x * 100)}%`
+}
+
+// A glance at the optimization signals (the same dimensions ModelMeter surfaces), so
+// the command shows value, not just discovery.
+function printSignals(summaries) {
+  if (summaries.length === 0) return
+  const s = summarizeSignals(summaries)
+  console.log(`\nOptimization signals (last 14 days, ${s.sessions} sessions, computed locally):`)
+  console.log(`  cache reuse:    ${pct(s.cacheRate)}`)
+  console.log(`  output share:   ${pct(s.outputShare)}`)
+  if (s.reasoningShare >= 0.005) console.log(`  reasoning:      ${pct(s.reasoningShare)} of output`)
+  if (s.topMcp) console.log(`  top MCP:        ${s.topMcp} (${pct(s.topMcpShare)} of tool tokens)`)
+  console.log(`  context bloat:  ${s.bloatedSessions} session${s.bloatedSessions === 1 ? '' : 's'} grew past 2x`)
+}
+
+function printRecommendations(summaries) {
   console.log('\nLocal recommendations (computed from your logs, nothing sent):')
   const recs = buildLocalRecommendations(summaries)
   if (recs.length === 0) {
@@ -233,7 +256,7 @@ if (cmd === 'doctor') {
     }),
   )
   if (args.includes('--recommendations')) {
-    printRecommendations(cutoffMs)
+    printRecommendations(readSummaries(cutoffMs))
     process.exit(0)
   }
   if (args.includes('--payload')) {
@@ -241,6 +264,7 @@ if (cmd === 'doctor') {
     process.env.MODELMETER_DRYRUN = '1'
     await runCollector() // prints the exact payload (counts only), then exits
   } else {
+    printSignals(readSummaries(cutoffMs))
     console.log(
       '\nRun `npx modelmeter-collect doctor --recommendations` for local optimization tips, or',
     )
@@ -249,5 +273,25 @@ if (cmd === 'doctor') {
   }
 }
 
-// Default: scan and report.
-await runCollector()
+// Default: with a token configured, scan and report (the hook / scheduled path).
+// Without one, this is a new user trying it - show the local value, no account needed.
+const cfg = readConfig()
+const configured = Boolean(process.env.MODELMETER_TOKEN || cfg.token)
+if (configured) {
+  await runCollector()
+} else {
+  const cutoffMs = Date.now() - 14 * 86_400_000
+  const summaries = readSummaries(cutoffMs)
+  console.log('ModelMeter: where your Claude Code and Codex tokens go. Local, token counts only.\n')
+  if (summaries.length === 0) {
+    console.log('No Claude Code or Codex session logs found in the last 14 days.')
+    console.log('Use one of those tools, then run `npx modelmeter-collect` again.')
+    process.exit(0)
+  }
+  printSignals(summaries)
+  printRecommendations(summaries)
+  console.log('\nThis ran entirely on your machine. Nothing was sent.')
+  console.log('Track it over time, across repos, or for your team: get a token at')
+  console.log('https://modelmeter.dev, then `npx modelmeter-collect init <token>`.')
+  process.exit(0)
+}

package/lib.mjs

@@ -589,3 +589,45 @@ export function buildLocalRecommendations(summaries) {
 
   return recs
 }
+
+// Headline optimization signals (metrics, not recommendations) for `doctor` to show
+// at a glance: the same dimensions ModelMeter surfaces, computed locally.
+export function summarizeSignals(summaries) {
+  const list = (summaries || []).filter(Boolean)
+  let uncached = 0
+  let cacheRead = 0
+  let cacheCreate = 0
+  let output = 0
+  let reasoning = 0
+  let bloated = 0
+  const tools = {}
+  for (const s of list) {
+    uncached += s.uncached
+    cacheRead += s.cacheRead
+    cacheCreate += s.cacheCreate
+    output += s.output
+    reasoning += s.reasoning || 0
+    const b = sessionBloat(s.contextSeq)
+    if (b && b.last5 > b.first5 * 2 && b.last5 > 30_000) bloated++
+    for (const [g, v] of Object.entries(s.tools || {})) {
+      tools[g] = (tools[g] || 0) + v.tokens
+    }
+  }
+  const inputTotal = uncached + cacheRead + cacheCreate
+  const total = inputTotal + output
+  const toolArr = Object.entries(tools)
+    .map(([tool, tok]) => ({ tool, tok }))
+    .sort((a, b) => b.tok - a.tok)
+  const toolTotal = toolArr.reduce((n, t) => n + t.tok, 0)
+  const topMcp = toolArr.find((t) => t.tool.startsWith('mcp:'))
+  return {
+    sessions: list.length,
+    totalTokens: total,
+    cacheRate: inputTotal > 0 ? cacheRead / inputTotal : 0,
+    outputShare: total > 0 ? output / total : 0,
+    reasoningShare: output > 0 ? reasoning / output : 0,
+    topMcp: topMcp ? topMcp.tool : null,
+    topMcpShare: topMcp && toolTotal > 0 ? topMcp.tok / toolTotal : 0,
+    bloatedSessions: bloated,
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modelmeter-collect",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Report LLM token usage from local Claude Code / Codex logs to ModelMeter. Token counts only, never prompts or keys.",
   "type": "module",
   "bin": {