tokenomics

you've heard of tokenmaxxing? well maybe you should try tokenminning instead

tokenomics is a small CLI that looks at the AI coding-agent sessions already sitting on your machine and helps you understand them. Run it with npx or bunx — nothing to install.

Status: the CLI analysis core is in place and harness adapters are landing one at a time — see Supported harnesses (✓ = adapter available). The browsable UI is still to come.

Usage

npx @ryanskidmore/tokenomics
# or
bunx @ryanskidmore/tokenomics

Works on macOS and Linux, under Node.js >= 22 or Bun.

The default command shows headline stats (sessions, turns, tokens by class, cache hit rate, cost, top models/tools, and a per-harness breakdown) behind a spinner while it loads.

Commands

• tokenomics — headline summary across every detected harness.
• tokenomics harnesses — lists every harness tokenomics knows about, whether it has an adapter yet, whether it was detected on this machine, its root data path, and its session count.
• tokenomics sessions — a table of recent (top-level) sessions. --limit <n> caps how many rows are shown (default 20); --sort recency|tokens|cost controls the order (default recency).
• tokenomics session <id> — turn-level detail for one session: time, model, input/output/cache-read/cache-write tokens, cache hit rate, context size, and tool call count, one row per turn. <id> accepts a unique prefix of a session id, not just the full id. Pass --messages to expand to message-level rows instead of turns.

Every data-bearing command accepts these shared filters:

• --harness <id> — restrict to one or more harnesses. Repeatable (--harness claude-code --harness codex) or comma-separated (--harness claude-code,codex).
• --since <when> — only include sessions active since a point in time: a relative offset (7d, 24h) or an absolute date (2026-01-01).

Pass --json to any command for machine-readable output (stable, documented-ish shapes — the default command dumps the full Stats object, sessions dumps a list of session summaries, and session <id> dumps the session plus its turns and messages). Other flags: --no-color, --debug, --help, --version. Output degrades gracefully when piped or redirected — no boxes, spinners, or color codes, just plain lines.

Supported harnesses

• Claude Code ✓
• Codex ✓
• opencode ✓
• pi ✓
• oh-my-pi ✓

Adapters land one harness per release; run tokenomics harnesses to see which ones have landed and whether they're detected on your machine. See docs/adapters.md for how a harness plugs in — the short version is one directory under src/adapters/<id>/ and one line in src/core/registry.ts.

Development

This project uses Bun (1.3.x) as its package manager, test runner, and bundler. Source lives in src/:

• src/cli.ts — the entrypoint; src/commands/ — one file per CLI command.
• src/core/ — the harness-agnostic core: the normalized data model (types.ts), the HarnessAdapter interface + AdapterContext (adapter.ts), the adapter registry (registry.ts), platform/path helpers (platform.ts), a streaming JSONL reader (jsonl.ts), TokenUsage maths (usage.ts), turn grouping (turns.ts), session loading (load.ts), and stats aggregation (stats.ts).
• src/adapters/<id>/ — one directory per harness adapter (see docs/adapters.md for how a harness plugs in).
• src/ui/ — reusable formatting/rendering helpers shared by every command.

Tests live in test/, mirroring src/. The CLI itself is built with citty for argument parsing, @clack/prompts for the intro/outro/note/ spinner UI, and picocolors for color — all three are bundled into dist/cli.js by bun build, so they're devDependencies rather than runtime dependencies. Core never uses a Bun-only API — only node:* modules — so the same src/ runs under plain Node.js >= 22 too.

From this directory (or use the root scripts, which run across every workspace):

bun run dev         # run the CLI from source
bun run build       # bundle src/cli.ts -> dist/cli.js (runs under Node >=22 or Bun)
bun run test        # run the test suite
bun run typecheck   # tsc --noEmit

Formatting and linting (bun run fmt, bun run lint) run from the repository root.

The published package must run under plain Node.js as well as Bun, so src/ never uses Bun-only runtime APIs. After building, sanity-check both runtimes:

node dist/cli.js
bun dist/cli.js

Releasing

See the repository README.

License

MIT — see LICENSE.