npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@renaissancemind/tokenflow

v0.2.7

Published

Local token usage collector for multi-device AI agent accounting.

Downloads

676

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Maintainers

caopulancaopulan

Keywords

Readme

TokenFlow teaser

npm install -g @renaissancemind/tokenflow && tokenflow init

Existing tokenusage installs keep working: the package still exposes a tokenusage command, reads existing ~/.tokenusage/config.json files, and accepts the old TOKENUSAGE_* environment variables as fallbacks.

Language: English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Español | Türkçe | Русский

Private, local-first token accounting for the AI agents you actually use.

npm Node.js TypeScript Privacy

Features - Install - Quick Start - Commands - Configuration - Development

TokenFlow is an installable local collector for multi-device AI-agent usage accounting. It scans local Codex, Claude Code, Gemini CLI, OpenCode, Kimi CLI, Qwen Code, Amp, Codebuff, Droid, Goose, Hermes, Kilo, OpenClaw, and Pi usage data, aggregates token counts into UTC half-hour buckets by agent and model, calculates known costs, and uploads only changed usage metadata to a TokenFlow server.

Prompts and responses stay on your machine. Uploaded payloads contain counts, model names, bucket timestamps, pricing status, and optional device metadata.

Preview

$ tokenflow status
TokenFlow status
Config: /Users/alice/.tokenflow/config.json
Server: https://tokenflow.renaissancemind.ai
Device: dev_...
Token: set (device)
Remote: linked
Local events: 1842
Local buckets: 37
Source codex: found (219 files) /Users/alice/.codex/sessions
Source claude: found (64 files) /Users/alice/.claude/projects
Source gemini: missing (0 files) /Users/alice/.gemini/tmp
Source opencode: found (1 files) /Users/alice/.local/share/opencode/opencode.db
Home: /Users/alice/.tokenflow

Features

  • 🔐 Local-first collection - reads agent logs locally and uploads metadata only.
  • 🤖 Multi-agent support - Codex, Claude Code, Gemini CLI, OpenCode, Kimi CLI, Qwen Code, Amp, Codebuff, Droid, Goose, Hermes, Kilo, OpenClaw, and Pi.
  • 📊 Half-hour UTC buckets - keeps local usage detail while dashboards can still summarize by day.
  • 💸 Cost-aware accounting - separates fresh input, cached input, cache creation, output, and reasoning output tokens.
  • 🧾 Unpriced model visibility - unknown models are counted and marked as unpriced instead of silently disappearing.
  • 🔁 Incremental automatic sync - installs a 10-minute macOS launchd or Linux systemd user timer and uploads only new or changed buckets after the initial backfill.
  • 🔑 Device login or API key upload - supports browser device linking and read_write API tokens.
  • 🛠️ Self-host friendly - point the CLI at any compatible TokenFlow server URL.

Supported Sources

| Source | Local data read | Notes | | --- | --- | --- | | Codex | ~/.codex/sessions/**/rollout-*.jsonl and archived session JSONL | Parses local rollout token events. | | Claude Code | ~/.claude/projects/**/*.jsonl | Parses project JSONL usage data. | | Gemini CLI | ~/.gemini/tmp/**/chats/session-*.json | Parses Gemini session JSON files. | | OpenCode | ~/.local/share/opencode/opencode.db | Requires sqlite3 on PATH. | | Kimi CLI | ~/.kimi/sessions/*/*/wire.jsonl | Reads StatusUpdate.token_usage rows and ~/.kimi/config.json model metadata. | | Qwen Code | ~/.qwen/projects/*/chats/*.jsonl | Reads assistant usageMetadata rows. | | Amp | ~/.local/share/amp/threads/*.json | Reads usageLedger.events[] or assistant messages[].usage. | | Codebuff | ~/.config/manicode*/projects/**/chat-messages.json | Reads assistant metadata usage and run-state provider usage. | | Droid | ~/.factory/sessions/**/*.settings.json | Reads session token snapshots and keeps the latest snapshot per session. | | Goose | ~/.local/share/goose/sessions/sessions.db, macOS Application Support, or Block Goose data | Requires sqlite3 on PATH. | | Hermes | ~/.hermes/state.db | Requires sqlite3 on PATH. | | Kilo | ~/.local/share/kilo/kilo.db | Requires sqlite3 on PATH. | | OpenClaw | ~/.openclaw, ~/.clawdbot, ~/.moltbot, and ~/.moldbot JSONL sessions | Tracks model-change rows for following assistant usage. | | Pi | ~/.pi/agent/sessions/**/*.jsonl | Reads assistant message usage rows. |

TokenFlow intentionally does not upload source file paths, session IDs, prompts, or responses.

Install

TokenFlow requires Node.js 20 or newer.

npm install -g @renaissancemind/tokenflow

If you want OpenCode, Goose, Hermes, or Kilo support, make sure sqlite3 is available:

sqlite3 --version

From a local checkout before npm publication:

npm install
npm install -g .

npm install -g . runs the package prepare script, so the TypeScript CLI is compiled before npm links dist/cli.js.

Quick Start

1. Link this machine

tokenflow login

By default, login uses https://tokenflow.renaissancemind.ai. It prints a verification URL and user code, opens the browser when possible, stores the approved device token in ~/.tokenflow/config.json, then runs one initial sync. Use --device-name to avoid uploading your real hostname:

tokenflow login --device-name "Private Mac"

To use a self-hosted server:

tokenflow login --server-url http://127.0.0.1:8787

To link the machine without the initial upload:

tokenflow login --no-sync

2. Check what will be scanned

tokenflow status

status shows local source paths, parsed event counts, bucket counts, unpriced bucket counts, config location, and remote auth status when a token is configured.

3. Sync usage

tokenflow sync

sync scans local logs, aggregates half-hour usage buckets, uploads only new or changed buckets, records a sync heartbeat, and reports parsed events plus uploaded buckets. The local upload ledger lives in ~/.tokenflow/sync-state.json.

4. Install automatic sync

tokenflow init

init writes ~/.tokenflow/config.json, installs automatic sync every 10 minutes on macOS or Linux, then starts the browser device-link flow unless a token already exists. It also accepts --device-name:

tokenflow init --device-name "Private Mac"

API Token Mode

Browser device linking is convenient for personal machines. For servers, CI-style machines, or scripted installs, use a read_write API key from the TokenFlow server dashboard:

tokenflow init --server-url https://tokenflow.renaissancemind.ai --api-token tu_api_...

Only read_write keys can upload usage. read_only keys are for dashboards, API reads, and public heatmap embeds; the CLI rejects read-only keys during init and login.

Commands

tokenflow init --server-url https://tokenflow.renaissancemind.ai
tokenflow login --server-url https://tokenflow.renaissancemind.ai
tokenflow login --server-url https://tokenflow.renaissancemind.ai --api-token tu_api_...
tokenflow device-name "Private Mac"
tokenflow device-name "Private Mac" --remote
tokenflow device-name "Private Mac" --local-only
tokenflow sync
tokenflow status
tokenflow update [--source @renaissancemind/tokenflow@latest|/path/to/TokenFlow]
tokenflow logout

| Command | What it does | | --- | --- | | init | Writes config, installs auto-sync, and optionally starts login. | | login | Links a browser-approved device token or stores a validated upload API token, then runs an initial sync unless --no-sync is set. | | device-name | Updates the local device name used by future uploads. In an interactive terminal it asks once whether to update the current server device too; use --remote or --local-only for scripts. | | sync | Parses local usage, builds UTC half-hour buckets, uploads new or changed buckets, and updates lastSyncAt. | | status | Prints local config, source availability, bucket counts, auth status, and unpriced models. | | update | Reinstalls the global package and refreshes the auto-sync scheduler. | | logout | Removes local upload tokens while keeping non-secret config. |

Pricing Model

TokenFlow calculates costs locally before upload.

  • Built-in pricing covers known Codex, Claude, Gemini, OpenCode, and cc-switch-inspired third-party coding/provider model IDs including DeepSeek, Kimi K2, MiniMax, GLM, Qwen, Doubao, StepFun, MiMo, Grok, Mistral, and Cohere.
  • Unknown models are still counted and uploaded with pricing_status: "unpriced".
  • Unpriced buckets record cost as $0.000000 so token totals remain accurate and cost gaps stay visible.
  • Cost calculation follows ccusage-style token accounting: fresh input, output, cache read, cache creation, optional 200k+ pricing tiers, and 1-hour cache creation at 2x input price when a source reports cache creation duration.
  • For Codex and Gemini, cached input can be included in reported input and is separated before cost calculation to avoid double-counting.
  • Kimi CLI keeps kimi-for-coding as the displayed model, while pricing resolves to K2.5 before 2026-04-20T15:28:10.072Z and K2.6 after that cutoff, matching ccusage's documented mapping.

Configuration

Environment overrides:

| Variable | Purpose | | --- | --- | | TOKENFLOW_HOME | Local state directory. Defaults to ~/.tokenflow. | | TOKENFLOW_SERVER_URL | Default server URL. | | TOKENFLOW_AUTO_SYNC_COMMAND | Command written into launchd/systemd. Defaults to tokenflow sync --auto. | | TOKENFLOW_SYNC_MAX_BUCKETS | Maximum changed buckets uploaded per sync. Defaults to 60 to keep first-time backfills Cloudflare-friendly. | | TOKENFLOW_REQUEST_TIMEOUT_MS | HTTP request timeout for TokenFlow server calls. Defaults to 30000. | | TOKENFLOW_UPDATE_SOURCE | Package/source used by tokenflow update when --source is omitted. | | CODEX_HOME | Codex config home. Defaults to ~/.codex. | | CLAUDE_HOME | Claude config home. Defaults to ~/.claude. | | GEMINI_HOME | Gemini config home. Defaults to ~/.gemini. | | OPENCODE_DB | Explicit OpenCode SQLite database path. | | OPENCODE_HOME | OpenCode data home. Defaults to ~/.local/share/opencode. | | KIMI_DATA_DIR | Kimi data root, or comma-separated roots. Defaults to ~/.kimi. | | QWEN_DATA_DIR | Qwen data root, or comma-separated roots. Defaults to ~/.qwen. | | AMP_DATA_DIR | Amp data root, or comma-separated roots. Defaults to ~/.local/share/amp. | | CODEBUFF_DATA_DIR | Codebuff/Manicode data root or projects root, comma-separated. Defaults to ~/.config/manicode, ~/.config/manicode-dev, and ~/.config/manicode-staging. | | DROID_SESSIONS_DIR | Droid sessions root, or comma-separated roots. Defaults to ~/.factory/sessions. | | GOOSE_PATH_ROOT | Goose root used to resolve data/sessions/sessions.db. | | HERMES_HOME | Hermes home, or comma-separated homes. Defaults to ~/.hermes. | | KILO_DATA_DIR | Kilo data root, or comma-separated roots. Defaults to ~/.local/share/kilo. | | OPENCLAW_DIR | OpenClaw-compatible roots, comma-separated. Defaults to ~/.openclaw, ~/.clawdbot, ~/.moltbot, and ~/.moldbot. | | PI_AGENT_DIR | Pi agent sessions root, or comma-separated roots. Defaults to ~/.pi/agent/sessions. | | XDG_DATA_HOME | Used to resolve OpenCode data when OPENCODE_DB and OPENCODE_HOME are unset. |

Existing TOKENUSAGE_* variables are still accepted as compatibility fallbacks.

Local checkout in auto-sync

Before publishing to npm, pin the scheduler to this checkout:

TOKENFLOW_AUTO_SYNC_COMMAND="node /Users/chunqiu/Documents/workspace/TokenFlow/dist/cli.js sync --auto" \
  tokenflow init --server-url https://tokenflow.renaissancemind.ai

After publishing, the default scheduler command can use npm:

npx --yes @renaissancemind/tokenflow init --server-url https://tokenflow.renaissancemind.ai

Development

npm install
npm test
npm run typecheck
npm run build
node dist/cli.js status

The source is a small TypeScript CLI:

  • src/cli.ts - command routing and user-facing behavior.
  • src/file-scan.ts - local agent discovery and parsing entrypoint.
  • src/sources/* - source-specific parsers.
  • src/usage-buckets.ts - UTC bucket aggregation.
  • src/pricing.ts - pricing resolution and cost calculation.
  • src/api.ts - device flow, token validation, and ingest calls.
  • src/scheduler.ts - macOS launchd and Linux systemd timer installation.

Limitations

  • OpenCode, Goose, Hermes, and Kilo database reads require the sqlite3 CLI.
  • Qoder is not currently treated as a token source because ccusage has no Qoder adapter and public Qoder APIs expose credits/usage events rather than local input/output/cache token logs.
  • Automatic sync is installed only on macOS and Linux; other platforms can run tokenflow sync manually or wire their own scheduler.
  • Costs for unknown model IDs are intentionally marked unpriced until a pricing rule exists.

Documentation

This README is the primary user documentation for the CLI. For implementation details, start with the focused tests in test/ and the TypeScript modules in src/.

Contributing

Issues and pull requests are welcome. Please include a focused test for parser, pricing, scheduler, or command behavior changes.

License

No license file is currently included in this repository.

Acknowledgements

Parts of TokenFlow's implementation and product flow were informed by the excellent work in cc-switch and vibe-usage. Local-source discovery, token-field mapping, and pricing behavior also reference ccusage. These projects are MIT-licensed; see THIRD_PARTY_NOTICES.md.