tokenflex/ing
Docs

How TokenFlexing works

Three things make up the system: a local scanner (the CLI), a cloud sync API, and a dashboard with optional public sharing and leaderboard participation. None of them read your prompts or completions — only the usage blocks the AI tools themselves write to disk.

Architecture

Local-first. The CLI on your machine does the parsing. The cloud only sees the same numbers your provider dashboard would.

1 · Scan

The CLI measures local usage logs from Command Code, Claude Code, Codex CLI, OpenCode, Cline, Roo Code, and Gemini CLI. It separately detects other installed tools, and Cursor needs a CSV import or cookie-backed export before it can provide usage data. No prompts or completions touch our servers.

2 · Sync

One-time browser login pairs the device. The daemon pushes a normalised snapshot to your tokenflex.ing profile keyed by (user, source) so multiple machines roll up cleanly into one profile.

3 · Share

Public profile at /u/<handle>, optional leaderboard appearance, ASCII flex cards for X/HN screenshots. Privacy toggle: public / aggregate-only / private.

1 · Scan

The scanner walks 22 known AI-tool sources on each run. Tools fall into three buckets:

  • MeasuredUsage extracted locally. Today: Command Code, Claude Code, Codex CLI, OpenCode, Cline, Roo Code, and Gemini CLI. Cline and Gemini CLI do not expose per-message cost.
  • DetectedWe see the tool is installed but cannot extract usage yet. Today: Aider, Kilo Code, Windsurf, Continue, Zed, Amp, Antigravity, Copilot, Goose, Kiro, Mux, Crush, Kimi, and Hermes.
  • Setup requiredCursor is detected locally, but its subscription client does not expose usage there. Import a Cursor usage CSV or configure cookie-backed export before it becomes measured.
  • Not foundTool isn't installed on this machine. We surface this bucket explicitly so you can audit what you actually use.

Reads are read-only. No prompt content, no completion text — only the usage blocks each provider stamps onto assistant messages.

2 · Sync

Pairs this machine to your tokenflex.ing account once, then pushes rollups whenever sync runs. Sharing and leaderboard participation stay optional.

# pair + scan + sync in one shot
npx tokenflexing@latest connect

# just push the latest scan (after pairing)
npx tokenflexing@latest sync

# set up hourly auto-refresh + on-login
npx tokenflexing@latest daemon --install

The daemon writes a LaunchAgent on macOS or a Task Scheduler entry on Windows (or a systemd user timer on Linux). It runs every hour; macOS also runs once when the LaunchAgent loads at login. Logs go to /tmp/tokenflexing-sync.log. Idempotent — re-running sync is safe.

3 · Share

Three visibility tiers. Set once during onboarding; change anytime in Settings.

  • PublicHandle, totals, per-model breakdown all visible. Eligible for the leaderboard.
  • Aggregate onlyTotals visible — per-source / per-model hidden. Still leaderboard-eligible.
  • PrivateProfile hidden, off the leaderboard. Data still aggregates into your dashboard.

Tool support

Quick reference. Full matrix on the CLI page.

ToolHowStatus
Command CodeReads ~/.commandcode/**/*.jsonlMeasured
Claude CodeReads ~/.claude/projects/**/*.jsonlMeasured
Codex CLIReads ~/.codex/sessions/**/*.jsonlMeasured
OpenCodeReads local message JSON (tokens + cost)Measured
ClineReads local API events (tokens only; no cost)Measured
Roo CodeReads local API events (tokens + cost)Measured
Gemini CLIReads local chats (tokens incl. thoughts; no per-message cost)Measured
CursorCSV import or cookie-backed usage exportSetup required
Aider · Kilo Code · Windsurf · Continue · Zed · Amp · Antigravity · Copilot · Goose · Kiro · Mux · Crush · Kimi · HermesInstalled-tool presence onlyDetected only
Claude Desktop · ChatGPT DesktopNo local usage parser in the current CLINot scanned

Cursor · three sync paths

Cursor is subscription-billed and doesn't write per-message tokens to disk. Pick whichever sync path fits your habits — all three layer cleanly via newest-mtime-wins.

AHourly auto (cookie-backed export)
npx tokenflexing@latest setup-cursor-auto

One-time: paste your cursor.com session cookie. The hourly daemon fetches Cursor's usage-events CSV export while the cookie remains valid. No more manual exports.

BInstant pickup (watch mode)
npx tokenflexing@latest watch-cursor

Foreground process. Watches ~/Downloads for cursor*.csv / usage*.csv drops via fs.watch and auto-imports within 500ms. Run in a tab while you click Export.

COne-time CSV import
npx tokenflexing@latest import-cursor ~/Downloads/usage.csv

Export CSV from cursor.com/dashboard → Settings → Usage → Export. Pass the path to the CLI. Folds into the next scan as real tokens + cost.

Claude Desktop bridge

Claude Desktop (the macOS / Windows app for claude.ai) doesn't write a local usage log that TokenFlexing can measure. Installing Claude Codealongside it lets TokenFlexing measure Claude Code's own JSONL usage, but it does not turn Claude Desktop conversations into measured data. You can still install the MCP server in Claude Desktop to query the usage TokenFlexing has already measured.

# 1. Grab Claude Code (free with Pro/Max)
#    Download: https://claude.ai/download

# 2. Re-sync — Claude Code's JSONL is picked up automatically
npx tokenflexing@latest sync

Claude Desktop tier declaration is on the roadmap. Until then, the CLI deliberately does not estimate or attribute Desktop usage.

MCP wiring

tokenflexing mcp starts a Model Context Protocol stdio server (protocol 2024-11-05). Wire it into Claude Code, Cursor, or Claude Desktop and ask your agent "how much have I spent this week?" without leaving chat.

Install

Dry-run first (no --apply) to preview changes.
ClientConfig pathInstall
Command Code~/.commandcode/mcp.json
npx tokenflexing@latest install-hooks --apply --client command-code
Claude Code~/.claude/settings.json
npx tokenflexing@latest install-hooks --apply --client claude-code
Cursor~/.cursor/mcp.json
npx tokenflexing@latest install-hooks --apply --client cursor
Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%/Claude/ (Windows)
npx tokenflexing@latest install-hooks --apply --client claude-desktop

Tools exposed

Read tools require no auth · Action tools prompt before writing
  • get_my_statsPer-source rollups (today / week / month / all-time) read straight off disk. Read-only.
  • get_device_scanFull device inventory: every AI tool detected, parsed vs un-parsed status. Read-only.
  • get_flex_cardASCII share card with totals + your tokenflex.ing URL. Drop into chat. Read-only.
  • setup_deviceOpens the browser pairing flow. Action — prompts before writing.
  • refresh_statsRe-scans and pushes a fresh sync to the cloud. Action — runs `tokenflexing sync` under the hood.
  • install_daemonInstalls the hourly auto-refresh schedule. On macOS, the agent also runs when it loads at login. Action — writes to LaunchAgent / Task Scheduler / systemd user timer.
  • import_cursor_csvPass a CSV path; imports + verifies. Action — writes to ~/.config/tokenflexing/cursor-usage.csv.
  • install_hooksWires tokenflexing into another editor's MCP list. Action.

Multi-account

One machine can hold many accounts (personal + work). One account can sync from many machines.

# list every saved profile (active one marked)
npx tokenflexing@latest profile list

# switch the active profile
npx tokenflexing@latest profile use work

# pair the active profile to a new machine
npx tokenflexing@latest login --token tf_live_…

Each profile stores its own token under ~/.config/tokenflexing/profiles/<name>/token (chmod 600). Active pointer at ~/.config/tokenflexing/active.

Privacy + storage

Tokens never leave your machine unless you run sync or connect. The only network traffic is the rollup push.

  • ~/.commandcode/mcp.jsonCommand Code user-scoped MCP servers (after install-hooks --client command-code).
  • ~/.config/tokenflexing/profiles/<name>/tokenPer-profile cloud sync token (chmod 600).
  • ~/.config/tokenflexing/activeActive profile pointer. Edit via `profile use <name>`.
  • ~/.config/tokenflexing/cursor-usage.csvLatest Cursor CSV (chmod 600). Re-parsed on every scan.
  • ~/.config/tokenflexing/cursor-cookieCursor session cookie for API replay (chmod 600). Set via `setup-cursor-auto`.
  • ~/.config/tokenflexing/cursor-api.jsonNormalised snapshot of last Cursor API fetch. Parser picks newer of this vs the CSV.
  • ~/Library/LaunchAgents/com.tokenflexing.sync.plistmacOS daemon plist (after `daemon --install`).
  • /tmp/tokenflexing-sync.log + .errDaemon stdout / stderr.

Detailed privacy commitments at /privacy · security model at /security.

Roadmap

What we're building next. Public progress lives at /roadmap.

  • Claude Desktop tier declaration (Pro / Max / Team)Soon
  • ChatGPT Desktop CSV importSoon
  • Aider / Cline / Roo / Kilo / Gemini CLI parsersSoon
  • MCP usage-callback support for Claude DesktopLater
  • Team rollups + shared org leaderboardsLater
  • Public REST API for verified-profile readsLater

Deeper references

Filing a bug? Include tokenflexing --version and tokenflexing scan output.