tokensaver-cli

CLI for estimating text token usage and reporting historical Claude Code / Codex session token consumption.

Usage

npx tokensaver-cli "Estimate this prompt"
tokensaver-cli --file ./prompt.txt
tokensaver-cli analyze
tokensaver-cli analyze day --source codex
tokensaver-cli analyze --source codex --top 10
tokensaver-cli analyze --period week --date 2026-05-02
tokensaver-cli analyze week --json

Analyze

analyze scans local session logs and reports totals by source, model, tool category, tool name, and top sessions.

Default locations:

• Claude Code: ~/.claude/projects
• Codex: ~/.codex/sessions

Options:

• --table: print a human-readable table, default output mode
• --json: print JSON for scripts
• --source claude|codex: scan only one source
• --top N: limit session rankings, default 20; use --top all for all
• day|week|month|total: optional positional period, for example analyze day. week means the latest 7 days through the anchor date; month means the latest 30 days through the anchor date.
• --period day|week|month|total: filter sessions by date range, default day
• --date YYYY-MM-DD: anchor date for day, week, or month; default is today
• --dir PATH: override the session directory for the selected source
• --claude-dir PATH: override the Claude directory when scanning both
• --codex-dir PATH: override the Codex directory when scanning both

When running interactively without a positional period or --period, analyze prompts for day, week, month, or total. Non-interactive runs default to day.

Claude reports include both non-cache and cache-aware totals:

• Total: input + output
• Cache: cache_read + cache_creation
• WithCache: input + output + cache_read + cache_creation

Codex cache reads are reported separately but not added again to WithCache, because Codex cached input is already included in recorded input totals.

Tool-level token attribution is heuristic: when a turn uses multiple tools, the turn's tokens are split evenly across those tools. Source and model totals come from the recorded session token usage.

Codex reports also include execCommand details. calls is the observed command count; weighted_calls is the turn-attribution weight used for token splits. Breakdowns include command type, command text, parsed path/query, exit status, largest outputs, and slowest commands. When Codex marks a command as unknown, tokensaver applies a conservative fallback classifier for common command families such as build, test, typecheck, dev server, node eval, git, HTTP, process, terminal, browser control, and file mutation.