TokenLens

TokenLens is a Bun-first local token analytics tool for coding agents. It imports normalized usage events from supported local sources into a TokenLens SQLite database and serves a local dashboard.

Dashboard Preview

The preview uses synthetic demo data generated by TokenLens, not private agent usage data.

Scope

• Supports OpenCode opencode.db and Claude Code project transcripts.
• Imports detected local sources together by default, with per-source filtering available.
• Does not install agent plugins or hooks.
• Does not upload data or require authentication.

Requirements

• Bun 1.3 or newer.

Quick Start

Start the local dashboard without installing globally:

bun x @jasonzhaoww/tokenlens@latest serve

Install

Run without installing globally:

bun x @jasonzhaoww/tokenlens@latest --help

Or install the CLI globally:

bun add -g @jasonzhaoww/tokenlens@latest
tokenlens --help

Commands

Print the installed CLI version:

tokenlens --version

Sync all detected usage sources into TokenLens:

tokenlens sync

Sync a specific source:

tokenlens sync --source opencode
tokenlens sync --source claude-code

Start the local dashboard and API:

tokenlens serve

Inspect paths and import state:

tokenlens status

Run diagnostics:

tokenlens doctor

Export imported metadata:

tokenlens export --format json
tokenlens export --format csv --output usage.csv

Use explicit source paths:

tokenlens sync --opencode-db /path/to/opencode.db
tokenlens sync --claude-code-projects /path/to/.claude/projects

XDG Paths

TokenLens uses XDG-compliant paths by default on Linux:

• Config: $XDG_CONFIG_HOME/tokenlens/config.json, default ~/.config/tokenlens/config.json
• Data: $XDG_DATA_HOME/tokenlens/tokenlens.db, default ~/.local/share/tokenlens/tokenlens.db
• State: $XDG_STATE_HOME/tokenlens/, default ~/.local/state/tokenlens/
• Cache: $XDG_CACHE_HOME/tokenlens/, default ~/.cache/tokenlens/

Useful overrides:

TOKENLENS_HOME=/tmp/tokenlens tokenlens sync
TOKENLENS_OPENCODE_DB=/path/to/opencode.db tokenlens sync
OPENCODE_HOME=/path/to/opencode-data tokenlens sync
TOKENLENS_CLAUDE_CODE_PROJECTS=/path/to/.claude/projects tokenlens sync
TOKENLENS_CLAUDE_CODE_HOME=/path/to/.claude tokenlens sync

Development

Install dependencies:

bun install

Run the CLI from the workspace:

bun run tokenlens --help

Generate privacy-safe demo data for screenshots:

bun run demo:data
bun run demo:serve

The demo OpenCode database, Claude Code transcripts, and TokenLens data are written under .demo/ with synthetic project names. demo:serve resets .demo/tokenlens/ before starting so screenshots are generated from demo data only.

Reset generated demo data:

bun run demo:reset

Run tests:

bun test

Typecheck:

bun run typecheck

Build dashboard and CLI bundle:

bun run build

Build a standalone Bun executable:

bun run compile