Docs

How TokenFlexing works

Three things make up the system: a local scanner (the CLI), a cloud sync API, and a public dashboard + leaderboard. 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 reads JSONL / SQLite session logs from Claude Code, Codex CLI, OpenCode, and 25+ other tools. Token counts, model breakdowns, and dollar costs are computed locally. 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 25+ known AI-tool storage paths on each run. Tools fall into three buckets:

MeasuredReal token counts + per-message cost extracted. Today: Claude Code, Codex CLI, OpenCode, plus Cursor via cookie API or CSV import.
DetectedWe see the tool is installed but the parser is on the roadmap. Today: Cline, Roo, Kilo, Gemini CLI, Aider, Windsurf, Goose, Amp, and ~10 others.
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.

# 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. Logs go to /tmp/tokenflexing-sync.log. Idempotent — re-running sync is safe.

Tool support

Quick reference. Full matrix on the CLI page.

Tool	How	Status
Claude Code	Reads ~/.claude/projects/*.jsonl	Auto
Codex CLI	Reads ~/.codex/sessions/*.json	Auto
OpenCode (sst/opencode)	Reads ~/.local/share/opencode/storage/message/*.json	Auto
Cursor	Cookie API · CSV watch · one-time CSV	Manual
Claude Desktop	Bridged via Claude Code (see below)	Manual
ChatGPT Desktop	CSV import — roadmap	Roadmap
Aider · Cline · Roo · Kilo · Gemini CLI	Detected only — parsers in roadmap	Roadmap

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.

ADaily auto (cookie API)

npx tokenflexing@latest setup-cursor-auto

One-time: paste your cursor.com session cookie. The daemon refreshes Cursor data daily via the same API the dashboard uses. 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 per-message logs to disk on its own. But if you install Claude Code— Anthropic's free CLI / VS Code companion — alongside it, Claude Code logs every assistant message to ~/.claude/projects/*.jsonl against the same subscription quota. tokenflexing reads those JSONLs automatically. Confirmed working today.

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

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

Tier declaration (Pro $20 / Max $200 / Team) is in the roadmap so users without Claude Code still see a subscription floor. Until then, the bridge above is the canonical workaround.

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.

Client	Config path	Install
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 6 AM auto-refresh schedule. Action — writes to LaunchAgent / Task Scheduler.
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.

~/.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

Full CLI glossary — every command, flag, when to use it, what it prints.
Repo README ↗ — architecture, env setup, contributor notes.
CLI README ↗ — source-level docs for every parser + integration point.
npm package ↗

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