tokenflexing

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

npx tokenflexing@latest scan

tokenflexing is a local scanner that finds every AI coding tool on your machine, extracts token counts where the data is parseable, and surfaces the rest as "detected but no telemetry yet". Dollar figures are API-equivalent cost: what the price-basis tokens would cost at model API rates, not necessarily what you paid through a subscription. Codex reports its indexed-token headline separately from the observed new-turn tokens used for pricing. Supported session records can also contain conversation text; TokenFlexing extracts structured usage fields and does not include prompt or completion text in scan output or sync payloads.

It also ships an MCP server, a login/sync pair for pushing snapshots to your private tokenflex.ing dashboard and profile, and an opt-in daemon for hourly auto-refresh.

Contents

• Install
• Commands
• What scan detects
• Cloud sync
• MCP server
• Hourly 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 ≥ 22 so the authoritative Codex SQLite index is available on every supported platform. Works on macOS, Windows, and Linux (XDG paths).

Commands

| Command | What it does | | ------------------------------------ | ----------------------------------------------------------------------------------------------------------- | | tokenflexing (default) | Local-calendar Today / 7-day / 30-day / all-time token totals and API-equivalent cost. | | 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; makes one optional aggregate request for rank/archetype and works offline without it. | | 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 private dashboard and profile. | | tokenflexing connect | Scan, pair this device if needed, and sync. Does not install a daemon or edit editor configs. | | tokenflexing connect --with-daemon | Also install the opt-in hourly auto-refresh daemon. | | tokenflexing connect --with-mcp | Also register MCP in detected supported editors. | | tokenflexing mcp | Start the MCP stdio server. | | tokenflexing install-hooks --apply | Register tokenflexing as an MCP server in Command Code, Claude Code (default), Cursor, or Claude Desktop. | | tokenflexing daemon | Preview the hourly LaunchAgent, Task Scheduler, or systemd user-timer entry. | | tokenflexing daemon --install | Install hourly sync; macOS and Linux also run when the user session starts. | | tokenflexing daemon --uninstall | Remove the daemon. | | tokenflexing --version | Print the installed version. | | tokenflexing --help | Full usage. |

What scan detects

Fully measured (token counts + API-equivalent cost)

| Tool | Source | | ---------------- | ------------------------------------------------------------------------------------------------------------ | | Claude Code | ~/.claude/projects/**/*.jsonl | | Command Code | Eligible session JSONL under ~/.commandcode/ (prompt/checkpoint sidecars excluded) | | Codex CLI | ~/.codex/state_*.sqlite totals + timestamped sessions/**/*.jsonl and archived_sessions/*.jsonl windows | | 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's local app database exposes turn counts only. Importing a Cursor usage CSV—or explicitly configuring the cookie-backed usage refresh—adds the measured token and cost fields available in Cursor's dashboard export.

For Codex, every CLI/MCP/share output deliberately shows two accounting bases. Codex-accounted tokens use Codex's own thread index as the all-time floor, including context inherited by forked/sub-agent threads. If timestamped turns prove that a counter reset contains additional history beyond that compact state row, TokenFlexing adds only the proven excess and shows the state/excess split. Today / 7-day / 30-day are calendar-day windows in the scanner's reported IANA time zone and use timestamped observed new-turn deltas, so a resumed or forked thread cannot dump its inherited cumulative baseline into the current day. The window receipt is exact, reconciled, or partial depending on how much of the indexed total has timestamped activity evidence. API-equivalent cost uses the same de-duplicated new-turn basis, so inherited parent context is not charged again merely because a child thread carried it forward. A separate cost-coverage status says whether that observed price basis is exact or partial. Model rows also label family-inferred and fallback-estimate rate bases, so a family match or generic estimate is never presented as an exact published rate card.

If the Codex state database still cannot be read, the JSONL fallback scans both active and archived sessions. When a first cumulative snapshot has valid last_token_usage, that observed turn is priced and the known remainder is labeled inherited baseline. If the split is missing or inconsistent, the snapshot is labeled unpriced/unknown with partial cost coverage—not guessed to be inherited and not priced as a fresh turn. Those fallback windows remain explicitly partial/unreconciled.

Cloud sync

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

# push your local stats to your private dashboard and profile
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 versioned snapshot per source to /api/sync/device. Every snapshot includes scanner/window/cost provenance and the CLI version. Usage coverage is sent as firstUsageDay/lastUsageDay calendar dates plus the scanner's IANA time zone; the CLI does not pretend a local day began at UTC midnight. Real observed instants are retained only when a scanner actually has them. Before upload, the CLI blocks impossible calendar token windows (today <= 7-day <= 30-day <= all-time). After upload, it prints the server's submitted-to-accepted top-level token receipt, post-device dashboard rollup, and any top-level token/source clamp, normalization, or duplicate collapse. The web app stores device snapshots and rolls paired machines into one profile. Costs, events, model buckets, and provenance are still independently validated and normalized by the server; the detailed receipt currently covers token/source adjustments.

Safe first connection

# Scans local usage, pairs in your browser if needed, then syncs one snapshot.
# It does not create a scheduled task or change any editor config.
npx tokenflexing@latest connect

# Explicitly add either optional integration when you want it.
npx tokenflexing@latest connect --with-daemon
npx tokenflexing@latest connect --with-mcp

MCP server

Make your AI agent self-aware about its tokens and API-equivalent cost. Register tokenflexing as an MCP server in Command Code, Claude Code, Cursor, or any other MCP-capable client:

# preview what will be written (no changes yet)
npx tokenflexing@latest install-hooks

# Command Code: writes to ~/.commandcode/mcp.json
npx tokenflexing@latest install-hooks --client command-code --apply

# 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

# Claude Desktop: writes to its user-level config (not a project config)
npx tokenflexing@latest install-hooks --client claude-desktop --apply

# Command Code project-local: writes to .mcp.json in the current directory
npx tokenflexing@latest install-hooks --client command-code --apply --project

# Claude Code project-local: writes to .claude/settings.json
npx tokenflexing@latest install-hooks --apply --project

Claude Desktop config paths are ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%/Claude/claude_desktop_config.json on Windows, and ~/.config/Claude/claude_desktop_config.json on Linux. Quit and reopen Claude Desktop after applying the change.

After restarting your editor, your agent has three read-only insight tools:

| Tool | Use it when the user asks | | ----------------- | -------------------------------------------- | | get_my_stats | "What was my API-equivalent cost this week?" | | get_device_scan | "Which AI tools do I have installed?" | | get_flex_card | "Show me a card I can post." |

The server also exposes action tools: setup_device, refresh_stats, install_daemon, import_cursor_csv, and install_hooks. Those tools can pair or sync a device, schedule background sync, import a user-specified CSV, or change an MCP config; your agent should run them only when you explicitly ask.

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

Hourly auto-refresh

# macOS: installs a LaunchAgent at ~/Library/LaunchAgents/com.tokenflexing.sync.plist
# runs hourly and when you log in
tokenflexing daemon --install

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

# Linux: installs a systemd user timer
# starts with your user session, then runs hourly
tokenflexing daemon --install

# remove it on either platform
tokenflexing daemon --uninstall

The scheduled job invokes npx tokenflexing@latest sync 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 or stats — they are local disk reads.
• flex makes one optional POST to tokenflex.ing/api/flex-preview with aggregate totals, model ids, and source ids to fetch a provisional rank/archetype. It sends no prompts or completions and still renders if that request fails.
• login and sync contact only tokenflex.ing.
• Session records can contain message text, but only structured usage fields (token counts, model ids, timestamps, and accounting provenance) are extracted into results. Prompt and completion text are not included in scan output or sync payloads.
• The MCP server returns only the same aggregated numbers. It does not return conversation text from the local records scanned to produce those aggregates.
• 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 Command Code, 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.17.0 — 2026-08-24

• Codex totals now prefer Codex's own state index, with timestamped session telemetry used for local-calendar Today / 7-day / 30-day windows.
• Codex output distinguishes provider-indexed tokens from de-duplicated observed new-turn tokens used for API-equivalent pricing, with explicit cost coverage.
• Non-exact Codex model rows show their family-inferred or fallback-estimate rate basis.
• The emergency JSONL fallback uses first-event last_token_usage and does not price inherited cumulative context as a fresh turn.
• Sync payload v2 includes CLI/scanner versions, coverage provenance, and calendar-window status.
• Sync provenance preserves local usage days with their IANA time zone instead of fabricating UTC boundary timestamps.
• The CLI validates window invariants before upload and prints a submitted-to-accepted server receipt with explicit top-level token/source adjustments.
• Cost copy now says API-equivalent instead of implying subscription users paid the displayed amount.
• Documented the optional aggregate network request made by flex.

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 schedule now invokes npx tokenflexing@latest sync 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 [email protected]).

License

MIT © 2026 Khadin Akbar