tokenflexing 1.1.0 → 1.2.0

package/README.md

@@ -1,138 +1,207 @@
-# tokenflex
+# tokenflexing
 
-Show off your AI token usage. Universal CLI for Claude Code, Codex, Cursor, and more.
+> Show off your AI token usage. Universal CLI for Claude Code, Codex, Cursor, OpenCode, and 20+ other AI tools.
+
+[![npm version](https://img.shields.io/npm/v/tokenflexing.svg?color=ff6f00)](https://www.npmjs.com/package/tokenflexing)
+[![npm downloads](https://img.shields.io/npm/dm/tokenflexing.svg)](https://www.npmjs.com/package/tokenflexing)
+[![Node](https://img.shields.io/badge/node-%E2%89%A518-43853d?logo=node.js)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](#license)
 
 ```bash
-npx tokenflex@latest scan
+npx tokenflexing@latest scan
 ```
 
-Scans your entire device for AI tool usage data, extracts token counts where possible, and shows everything else it detected. **Never reads prompts or completions — only usage/token blocks.**
+`tokenflexing` is a pure-local scanner that finds every AI coding tool on your machine, extracts token counts and cost where the data is parseable, and surfaces the rest as "detected but no telemetry yet". It never reads your prompts or model completions — only the usage/token blocks already written to disk by the tools themselves.
 
-## Commands
+It also ships an [MCP server](https://modelcontextprotocol.io), a `login`/`sync` pair for pushing snapshots to your [tokenflexing.com](https://tokenflexing.com) profile, and an `--install` flag that wires a daily auto-refresh into `launchd` (macOS) or Task Scheduler (Windows).
 
-| Command | What |
-|---|---|
-| `tokenflex` / `tokenflex stats` | Today / 7-day / 30-day / all-time dollar + token spend per source, per model |
-| `tokenflex scan` | Universal device inventory — measured, detected, and not-found in one view |
-| `tokenflex flex` | Shareable ASCII card — drop in tweets, HN comments, or Slack |
-| `tokenflex daemon` | Preview the daily auto-refresh LaunchAgent (macOS) or Task Scheduler entry (Windows) |
-| `tokenflex daemon --install` | Install the daemon (runs `tokenflex scan` at 6:00 AM daily) |
-| `tokenflex daemon --uninstall` | Remove the daemon |
-| `tokenflex mcp` | Start MCP server — Claude Code, Cursor, and any MCP-capable agent can call tokenflex tools natively |
-| `tokenflex install-hooks --apply` | Register tokenflex as an MCP server in Claude Code or Cursor settings |
-| `tokenflex --help` | Usage |
-
-## What `tokenflex scan` detects
-
-| Tool | Status |
-|---|---|
-| **Claude Code** | ✅ Token counts + cost extracted (`~/.claude/projects/**/*.jsonl`) |
-| **Codex CLI** | ✅ Token counts + cost extracted (`~/.codex/sessions/**/*.jsonl`) |
-| **Cursor** | 🔍 Detected — SQLite `state.vscdb` reader planned |
-| **Claude Desktop** | 🔍 Detected — Electron, no token events exposed |
-| **ChatGPT Desktop** | 🔍 Detected — Electron, conversation data only |
-| **Windsurf (Codeium)** | 🔍 Detected — structured token log not exposed yet |
-| **Continue.dev** | 🔍 Detected — telemetry parser planned |
-| **Aider** | 🔍 Detected — cost-line parser planned |
-| **Cline** | 🔍 Detected — `ui_messages.json` task parser planned |
-| **Roo Code** | 🔍 Detected — `ui_messages.json` task parser planned |
-| **Kilo Code** | 🔍 Detected — `ui_messages.json` task parser planned |
-| **Zed AI** | 🔍 Detected — SQLite `threads.db` reader planned |
-| **Gemini CLI** | 🔍 Detected — `~/.gemini/tmp/*.jsonl` parser planned |
-| **OpenCode** | 🔍 Detected — `opencode/storage/message/*.json` parser planned |
-| **Amp** | 🔍 Detected — `amp/threads/T-*.json` parser planned |
-| **Antigravity (Google)** | 🔍 Detected — session cache format TBD |
-| **GitHub Copilot** | 🔍 Detected — OTEL trace extraction planned |
-| **Goose (Block)** | 🔍 Detected — SQLite `sessions.db` reader planned |
-| **Kiro (Amazon)** | 🔍 Detected — `~/.kiro/sessions/cli/*.json` parser planned |
-| **Mux** | 🔍 Detected — `session-usage.json` parser planned |
-| **OpenClaw** | 🔍 Detected — JSONL agent sessions parser planned |
-| **Crush** | 🔍 Detected — `projects.json` parser planned |
-| **Kimi (Moonshot)** | 🔍 Detected — `wire.jsonl` parser planned |
-| **Hermes** | 🔍 Detected — SQLite `state.db` reader planned |
-
-macOS, Windows, and Linux (XDG) paths covered.
+---
 
-## Why local files?
+## Contents
+
+- [Install](#install)
+- [Commands](#commands)
+- [What `scan` detects](#what-scan-detects)
+- [Cloud sync](#cloud-sync)
+- [MCP server](#mcp-server)
+- [Daily auto-refresh](#daily-auto-refresh)
+- [Privacy](#privacy)
+- [Why local files?](#why-local-files)
+- [Changelog](#changelog)
+- [License](#license)
 
-Provider Admin APIs (Anthropic / OpenAI) require **organization admin** keys that individual developers don't have. Local session JSONL files contain per-turn usage data for **anyone** using Claude Code or Codex CLI on any plan — no org key needed.
+---
 
 ## Install
 
 ```bash
-# one-shot
-npx tokenflex@latest stats
+# one-shot, no install
+npx tokenflexing@latest scan
 
 # or install globally
-npm install -g tokenflex
-tokenflex scan
+npm install -g tokenflexing
+tokenflexing scan
 ```
 
-Requires Node ≥ 18.
+Requires **Node ≥ 18**. Works on macOS, Windows, and Linux (XDG paths).
 
-## MCP Server (agent-native access)
+---
 
-Register tokenflex as an MCP server so Claude Code, Cursor, and any MCP-capable agent can query your stats inline:
+## Commands
 
-```bash
-# Dry-run — shows what will be written
-npx tokenflex@latest install-hooks
+| Command | What it does |
+|---|---|
+| `tokenflexing` *(default)* | Today / 7-day / 30-day / all-time dollar + token totals. |
+| `tokenflexing stats` | Same as above, with a per-model breakdown for every source. |
+| `tokenflexing scan` | Full device inventory — measured, detected, and not-found tools side by side. |
+| `tokenflexing flex` | Shareable ASCII card for X, HN, or Slack. |
+| `tokenflexing login` | Browser-based pairing with your tokenflexing.com account. |
+| `tokenflexing login --token <tok>` | Skip the browser flow — paste a token from tokenflexing.com/settings. |
+| `tokenflexing sync` | Push current local stats to your public profile. |
+| `tokenflexing mcp` | Start the MCP stdio server. |
+| `tokenflexing install-hooks --apply` | Register `tokenflexing` as an MCP server in Claude Code (default) or Cursor (`--client cursor`). |
+| `tokenflexing daemon` | Preview the daily-refresh LaunchAgent / Task Scheduler entry. |
+| `tokenflexing daemon --install` | Install it (runs `tokenflexing scan` at 6:00 AM daily via `npx`). |
+| `tokenflexing daemon --uninstall` | Remove the daemon. |
+| `tokenflexing --version` | Print the installed version. |
+| `tokenflexing --help` | Full usage. |
+
+---
+
+## What `scan` detects
+
+### Fully measured (token counts + cost extracted)
+
+| Tool | Source |
+|---|---|
+| **Claude Code** | `~/.claude/projects/**/*.jsonl` |
+| **Codex CLI** | `~/.codex/sessions/**/*.jsonl` |
+| **OpenCode** | `~/.local/share/opencode/opencode.db` (when sessions exist) |
+
+### Detected (presence + path, telemetry parser in progress)
 
-# Write MCP entry to ~/.claude/settings.json (Claude Code)
-npx tokenflex@latest install-hooks --apply
+Cursor · Claude Desktop · ChatGPT Desktop · Windsurf · Continue.dev · Aider · Cline · Roo Code · Kilo Code · Zed AI · Gemini CLI · Amp · Antigravity (Google) · GitHub Copilot · Goose (Block) · Kiro (Amazon) · Mux · OpenClaw · Crush · Kimi (Moonshot) · Hermes
 
-# Write to ~/.cursor/mcp.json (Cursor)
-npx tokenflex@latest install-hooks --client cursor --apply
+Cursor is intentionally turn-count only because Cursor is subscription-based and stores no per-message token data locally.
 
-# Project-local (writes to .claude/settings.json in current dir)
-npx tokenflex@latest install-hooks --apply --project
+---
+
+## Cloud sync
+
+```bash
+# one-time browser login — opens https://tokenflexing.com/cli-auth
+npx tokenflexing@latest login
+
+# push your local stats to your public profile + the global leaderboard
+npx tokenflexing@latest sync
 ```
 
-After restarting your editor, your agent gets three new tools:
+The token is stored at `~/.config/tokenflexing/token` (or `%APPDATA%/tokenflexing/token` on Windows). You only log in once; the token persists across reboots and only needs to be re-issued if you revoke it from [tokenflexing.com/settings](https://tokenflexing.com/settings).
 
-| Tool | What it does |
-|---|---|
-| `get_my_stats` | Token spend by period and model |
-| `get_device_scan` | Which AI tools are installed + measured |
-| `get_flex_card` | Shareable one-liner for X / HN / Slack |
+`sync` reads the same data that `scan` produces and POSTs a snapshot per source to `/api/sync/device`. The web app stores it in the `device_stats` table keyed by `(user_id, source)`, and the dashboard surfaces rows from every device you've paired — so usage from your laptop, desktop, and CI box all roll up into one profile.
 
-Or run the MCP server directly (for custom integrations):
+---
+
+## MCP server
+
+Make your AI agent self-aware about how much it costs to run. Register `tokenflexing` as an MCP server in Claude Code, Cursor, or any other [MCP-capable](https://modelcontextprotocol.io) client:
 
 ```bash
-npx tokenflex@latest mcp
+# preview what will be written (no changes yet)
+npx tokenflexing@latest install-hooks
+
+# Claude Code: writes to ~/.claude/settings.json
+npx tokenflexing@latest install-hooks --apply
+
+# Cursor: writes to ~/.cursor/mcp.json
+npx tokenflexing@latest install-hooks --client cursor --apply
+
+# project-local: writes to .claude/settings.json in the current directory
+npx tokenflexing@latest install-hooks --apply --project
 ```
 
-MCP entry format for manual config:
+After restarting your editor, your agent has three new tools:
+
+| Tool | Use it when the user asks |
+|---|---|
+| `get_my_stats` | "How much did I burn on AI this week?" |
+| `get_device_scan` | "Which AI tools do I have installed?" |
+| `get_flex_card` | "Show me a card I can post." |
+
+Manual MCP config (if you prefer editing JSON):
 
 ```json
 {
   "mcpServers": {
-    "tokenflex": { "command": "npx", "args": ["-y", "tokenflex@latest", "mcp"], "type": "stdio" }
+    "tokenflexing": {
+      "command": "npx",
+      "args": ["-y", "tokenflexing@latest", "mcp"],
+      "type": "stdio"
+    }
   }
 }
 ```
 
+Or run the server directly for custom integrations:
+
+```bash
+npx tokenflexing@latest mcp
+```
+
+---
+
 ## Daily auto-refresh
 
 ```bash
-# macOS: installs a LaunchAgent that runs tokenflex scan at 6 AM
-tokenflex daemon --install
+# macOS: installs a LaunchAgent at ~/Library/LaunchAgents/com.tokenflexing.sync.plist
+tokenflexing daemon --install
 
-# Windows: creates a Task Scheduler entry
-tokenflex daemon --install
+# Windows: creates a Task Scheduler entry "Tokenflexing Sync"
+tokenflexing daemon --install
 
-# Remove
-tokenflex daemon --uninstall
+# remove it on either platform
+tokenflexing daemon --uninstall
 ```
 
-Cloud sync (`tokenflex login` → push to tokenflexing.com profile) ships in v0.3.
+The scheduled job invokes `npx tokenflexing@latest scan` rather than a hard-coded local path, so it keeps working across upgrades, across `node` versions, and on machines that don't have the package installed globally. Logs land at `/tmp/tokenflexing-sync.log` on macOS / Linux.
+
+---
 
 ## Privacy
 
-- No network calls. Pure local read.
-- Only usage blocks (token counts, model ids) are parsed — never message content.
-- `tokenflex daemon` logs to `/tmp/tokenflex-sync.log` only.
+- **No network calls** during `scan`, `stats`, or `flex` — pure local read.
+- `login` and `sync` only contact `tokenflexing.com`.
+- Only **usage blocks** (token counts, model ids, timestamps) are parsed — never message content, never prompts, never completions.
+- The MCP server returns only the same aggregated numbers; it never reads your conversation history.
+- The daemon logs to `/tmp/tokenflexing-sync.log` and nowhere else.
+
+---
+
+## Why local files?
+
+Provider Admin APIs (Anthropic, OpenAI) require **organization admin** keys that individual developers don't have. From the Anthropic docs verbatim: *"The Admin API is unavailable for individual accounts."* OpenAI: *"Only Organization Owners can create and use Admin API keys."*
+
+Local session JSONL and SQLite files contain per-turn usage data for **anyone** running Claude Code, Codex CLI, or OpenCode — on any plan, with no org key required. That's why `scan` parses files first and only falls back to API connectors when you explicitly add one.
+
+---
+
+## Changelog
+
+### 1.1.0 — 2026-05-17
+
+- Renamed package from `tokenflex` to `tokenflexing` (the original name was taken on npm).
+- **Fixed daemon path bug**: the LaunchAgent / Task Scheduler plist used to embed the developer's local file path resolved from `import.meta.url`, which never existed for end users. The plist now invokes `npx tokenflexing@latest scan`, derived from the same directory as `process.execPath` so it works on any host.
+- Cloud sync (`login` + `sync`) promoted from "ships in v0.3" to live.
+- OpenCode SQLite reader added; Cursor detection reports turn counts (Cursor is subscription-based).
+- Config directory moved from `~/.config/tokenflex` to `~/.config/tokenflexing`.
+- All help text, log messages, and MCP entry names updated to the new binary.
+
+### 0.3.0 — 2026-05-16
+
+Initial preview release as `tokenflex` (now superseded by `tokenflexing@1.1.0`).
+
+---
 
 ## License
 
-MIT
+MIT © 2026 Khadin Akbar

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenflexing",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Show off your AI token usage. CLI for Claude Code, Codex, Cursor, OpenCode and more.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -11,8 +11,9 @@ import {
 import { join, dirname } from "node:path";
 import { homedir, userInfo } from "node:os";
 import { execFileSync } from "node:child_process";
-// node:readline used for interactive prompts in commandLogin
-import { createInterface } from "node:readline";
+// commandLogin currently uses browser-based polling rather than interactive
+// stdin, so node:readline is intentionally not imported. Re-add if/when we
+// reintroduce an interactive `--token` prompt fallback.
 
 /* ───── Platform ───────────────────────────────────────────────── */
 
@@ -459,7 +460,7 @@ function commandMcp() {
   function handle(req) {
     const { method, id, params } = req;
     if (method === "initialize") {
-      send({ jsonrpc: "2.0", id, result: { protocolVersion: "2024-11-05", capabilities: { tools: {} }, serverInfo: { name: "tokenflexing", version: "1.1.0" } } });
+      send({ jsonrpc: "2.0", id, result: { protocolVersion: "2024-11-05", capabilities: { tools: {} }, serverInfo: { name: "tokenflexing", version: "1.2.0" } } });
     } else if (method === "notifications/initialized" || method === "ping") {
       if (id !== undefined) send({ jsonrpc: "2.0", id, result: {} });
     } else if (method === "tools/list") {
@@ -919,23 +920,39 @@ async function commandSync() {
   console.log(`${c.bold}tokenflexing sync${c.reset}`);
   console.log("");
 
-  // Collect parsed source data
-  const sources = collectSources();
+  // Collect every detected source (measured + detection-only). Detection-only
+  // rows ship with zero counts and `detected: true` so the dashboard knows
+  // the tool is installed even though we can't measure its tokens yet.
+  const sources = collectAllSources();
   if (!sources.length) {
-    console.log(`${c.faint}Nothing to sync — no parseable sources found.${c.reset}`);
+    console.log(`${c.faint}Nothing to sync — no AI tools detected on this device.${c.reset}`);
     console.log("");
     return;
   }
 
-  const scans = sources.map((s) => ({
-    source:  s.id,
-    events:  s.stats.events,
-    input:   s.stats.input,
-    output:  s.stats.output,
-    cached:  s.stats.cached,
-    cost:    s.stats.cost,
-    models:  Object.fromEntries(s.stats.models),
-  }));
+  const scans = sources.map((s) => {
+    if (s.detected) {
+      return {
+        source:   s.id,
+        detected: true,
+        events:   0,
+        input:    0,
+        output:   0,
+        cached:   0,
+        cost:     0,
+        models:   {},
+      };
+    }
+    return {
+      source:  s.id,
+      events:  s.stats.events,
+      input:   s.stats.input,
+      output:  s.stats.output,
+      cached:  s.stats.cached,
+      cost:    s.stats.cost,
+      models:  Object.fromEntries(s.stats.models),
+    };
+  });
 
   let res;
   try {
@@ -967,12 +984,97 @@ function collectSources() {
     .map((r) => ({ id: r.id, name: r.name, stats: r.stats }));
 }
 
-function commandVersion() { console.log("1.1.0"); }
+/**
+ * Return every source the scan touched: measured (with token data) AND
+ * detection-only (presence confirmed but no usage parser yet). Detection-only
+ * entries get zero counts and a `detected: true` flag so the web dashboard can
+ * surface them as "installed, telemetry coming" rows instead of silently
+ * dropping them.
+ */
+function collectAllSources() {
+  return runScan()
+    .filter((r) => r.found)
+    .map((r) => ({
+      id: r.id,
+      name: r.name,
+      detected: !r.hasData,
+      stats: r.hasData ? r.stats : null,
+    }));
+}
+
+/**
+ * `tokenflexing connect` — the one-command onboarding flow.
+ * Bundles scan + login (if needed) + sync + a friendly nudge to install the
+ * daily-refresh daemon. Targeted at first-time users who don't want to read
+ * the full command reference.
+ */
+async function commandConnect() {
+  console.log("");
+  console.log(`${c.bold}tokenflexing connect${c.reset} ${c.faint}— one-command setup${c.reset}`);
+  console.log("");
+
+  // ── Step 1: scan ────────────────────────────────────────────────
+  console.log(`${c.faint}Step 1/3 · Scanning this machine for AI tools…${c.reset}`);
+  const scan     = runScan();
+  const measured = scan.filter((r) => r.hasData);
+  const detected = scan.filter((r) => r.found && !r.hasData);
+
+  if (!measured.length && !detected.length) {
+    console.log("");
+    console.log(`${c.faint}No AI tools detected on this device.${c.reset}`);
+    console.log(`${c.faint}Install Claude Code, Codex CLI, Cursor, OpenCode, Antigravity,${c.reset}`);
+    console.log(`${c.faint}Windsurf, Aider, or any of the 20+ supported tools and re-run.${c.reset}`);
+    console.log("");
+    return;
+  }
+
+  console.log(`${c.green}✓${c.reset} Found ${c.bold}${measured.length}${c.reset} measured · ${c.bold}${detected.length}${c.reset} detected`);
+  for (const m of measured) {
+    const cost = m.stats?.cost ?? 0;
+    console.log(`  ${c.green}●${c.reset} ${pad(m.name, 22)} ${c.faint}${fmtUsd(cost)} all-time${c.reset}`);
+  }
+  for (const d of detected) {
+    console.log(`  ${c.yellow}◎${c.reset} ${pad(d.name, 22)} ${c.faint}detected · telemetry parser pending${c.reset}`);
+  }
+  console.log("");
+
+  // ── Step 2: login if needed ─────────────────────────────────────
+  let token = loadToken();
+  if (!token) {
+    console.log(`${c.faint}Step 2/3 · Pairing this device with tokenflexing.com…${c.reset}`);
+    await commandLogin([]);
+    token = loadToken();
+    if (!token) {
+      console.log(`${c.faint}Connect aborted — could not pair this device.${c.reset}`);
+      console.log("");
+      return;
+    }
+  } else {
+    console.log(`${c.faint}Step 2/3 · Already paired with tokenflexing.com${c.reset} ${c.green}✓${c.reset}`);
+    console.log("");
+  }
+
+  // ── Step 3: sync ────────────────────────────────────────────────
+  console.log(`${c.faint}Step 3/3 · Pushing stats to your profile…${c.reset}`);
+  await commandSync();
+
+  // ── Daemon nudge ────────────────────────────────────────────────
+  console.log(`${c.bold}You're connected.${c.reset}`);
+  console.log("");
+  console.log(`Optional next steps:`);
+  console.log(`  ${c.green}tokenflexing daemon --install${c.reset}        ${c.faint}refresh daily at 6 AM${c.reset}`);
+  console.log(`  ${c.green}tokenflexing install-hooks --apply${c.reset}   ${c.faint}wire MCP into Claude Code${c.reset}`);
+  console.log(`  ${c.faint}View your profile: ${SITE}/dashboard${c.reset}`);
+  console.log("");
+}
+
+function commandVersion() { console.log("1.2.0"); }
 
 function commandHelp() {
   console.log("");
   console.log(`${c.bold}tokenflexing${c.reset}${c.faint} — show off your AI token usage${c.reset}`);
   console.log("");
+  console.log(`  ${c.green}tokenflexing connect${c.reset}            ${c.bold}one-command setup${c.reset} — scan + login + sync`);
   console.log(`  ${c.green}tokenflexing${c.reset}                    show stats (default)`);
   console.log(`  ${c.green}tokenflexing stats${c.reset}              breakdown per source + model`);
   console.log(`  ${c.green}tokenflexing scan${c.reset}               detect ALL AI tools on this device`);
@@ -1009,6 +1111,7 @@ export async function main(argv) {
     case undefined:       return commandStats();
     case "scan":          return commandScan();
     case "flex":          return commandFlex();
+    case "connect":       return commandConnect();
     case "daemon":        return commandDaemon(argv.slice(1));
     case "mcp":           return commandMcp();
     case "install-hooks": return commandInstallHooks(argv.slice(1));