tokenflexing

Show off your AI token usage. Universal CLI for Claude Code, Codex, Cursor, OpenCode, and 20+ other AI tools.

npx tokenflexing@latest scan

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.

It also ships an MCP server, a login/sync pair for pushing snapshots to your tokenflex.ing profile, and an --install flag that wires a daily auto-refresh into launchd (macOS) or Task Scheduler (Windows).

---

Contents

• Install
• Commands
• What scan detects
• Cloud sync
• MCP server
• Daily auto-refresh
• Privacy
• Why local files?
• Changelog
• License

---

Install

# one-shot, no install
npx tokenflexing@latest scan

# or install globally
npm install -g tokenflexing
tokenflexing scan

Requires Node ≥ 18. Works on macOS, Windows, and Linux (XDG paths).

---

Commands

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 tokenflex.ing account.
tokenflexing login --token <tok>	Skip the browser flow — paste a token from tokenflex.ing/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)

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

Cursor is intentionally turn-count only because Cursor is subscription-based and stores no per-message token data locally.

---

Cloud sync

# one-time browser login — opens https://tokenflex.ing/cli-auth
npx tokenflexing@latest login

# push your local stats to your public profile + the global leaderboard
npx tokenflexing@latest sync

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 tokenflex.ing/settings.

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.

---

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 client:

# 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

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):

{
  "mcpServers": {
    "tokenflexing": {
      "command": "npx",
      "args": ["-y", "tokenflexing@latest", "mcp"],
      "type": "stdio"
    }
  }
}

Or run the server directly for custom integrations:

npx tokenflexing@latest mcp

---

Daily auto-refresh

# macOS: installs a LaunchAgent at ~/Library/LaunchAgents/com.tokenflexing.sync.plist
tokenflexing daemon --install

# Windows: creates a Task Scheduler entry "Tokenflexing Sync"
tokenflexing daemon --install

# remove it on either platform
tokenflexing daemon --uninstall

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 during scan, stats, or flex — pure local read.
• login and sync only contact tokenflex.ing.
• 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 © 2026 Khadin Akbar