Token Savings Analytics

rtk gain shows how many tokens RTK has saved across all your commands, with daily, weekly, and monthly breakdowns.

Quick reference

bash

# Default summary
rtk gain

# Temporal breakdowns
rtk gain --daily          # all days since tracking started
rtk gain --weekly         # aggregated by week
rtk gain --monthly        # aggregated by month
rtk gain --all            # all breakdowns at once

# Classic flags
rtk gain --graph          # ASCII graph, last 30 days
rtk gain --history        # last 10 commands
rtk gain --quota          # monthly quota savings estimate (default tier: 20x)
rtk gain --quota -t pro   # use pro tier token budget for estimate

# Export
rtk gain --all --format json > savings.json
rtk gain --all --format csv  > savings.csv

Daily breakdown

bash

rtk gain --daily

📅 Daily Breakdown (3 days)
════════════════════════════════════════════════════════════════
Date            Cmds      Input     Output      Saved   Save%
────────────────────────────────────────────────────────────────
2026-01-28        89     380.9K      26.7K     355.8K   93.4%
2026-01-29       102     894.5K      32.4K     863.7K   96.6%
2026-01-30         5        749         55        694   92.7%
────────────────────────────────────────────────────────────────
TOTAL            196       1.3M      59.2K       1.2M   95.6%

Cmds: RTK commands executed
Input: Estimated tokens from raw command output
Output: Actual tokens after filtering
Saved: Input - Output (tokens that never reached the LLM)
Save%: Saved / Input × 100

Weekly and monthly breakdowns

bash

rtk gain --weekly
rtk gain --monthly

Same columns as daily, aggregated by Sunday-Saturday week or calendar month.

Export formats

Format	Flag	Use case
`text`	default	Terminal display
`json`	`--format json`	Programmatic analysis, dashboards
`csv`	`--format csv`	Excel, Python/R, Google Sheets

JSON structure:

json

{
  "summary": {
    "total_commands": 196,
    "total_input": 1276098,
    "total_output": 59244,
    "total_saved": 1220217,
    "avg_savings_pct": 95.62
  },
  "daily": [...],
  "weekly": [...],
  "monthly": [...]
}

Typical savings by command

Command	Typical savings	Mechanism
`git status`	77-93%	Compact stat format
`eslint`	84%	Group by rule
`jest`	94-99%	Show failures only
`vitest`	94-99%	Show failures only
`find`	75%	Tree format
`pnpm list`	70-90%	Compact dependencies
`grep`	70%	Truncate + group

How token estimation works

RTK estimates tokens using text.len() / 4 (4 characters per token average). This is accurate to ±10% compared to actual LLM tokenization — sufficient for trend analysis.

Input Tokens  = estimate_tokens(raw_command_output)
Output Tokens = estimate_tokens(rtk_filtered_output)
Saved Tokens  = Input - Output
Savings %     = (Saved / Input) × 100

Database

Savings data is stored locally in SQLite:

Location: ~/.local/share/rtk/history.db (Linux / macOS)
Retention: 90 days (automatic cleanup)
Scope: Global across all projects and Claude sessions

bash

# Inspect raw data
sqlite3 ~/.local/share/rtk/history.db \
  "SELECT timestamp, rtk_cmd, saved_tokens FROM commands
   ORDER BY timestamp DESC LIMIT 10"

# Backup
cp ~/.local/share/rtk/history.db ~/backups/rtk-history-$(date +%Y%m%d).db

# Reset
rm ~/.local/share/rtk/history.db    # recreated on next command

Analysis workflows

bash

# Weekly progress: generate a CSV report every Monday
rtk gain --weekly --format csv > reports/week-$(date +%Y-%W).csv

# Monthly budget review
rtk gain --monthly --format json | jq '.monthly[] |
  {month, saved_tokens, quota_pct: (.saved_tokens / 6000000 * 100)}'

# Cron: daily JSON snapshot for a dashboard
0 0 * * * rtk gain --all --format json > /var/www/dashboard/rtk-stats.json

Python/pandas:

python

import pandas as pd
import subprocess

result = subprocess.run(['rtk', 'gain', '--all', '--format', 'csv'],
                       capture_output=True, text=True)
lines = result.stdout.split('\n')
daily_start = lines.index('# Daily Data') + 2
daily_end = lines.index('', daily_start)
daily_df = pd.read_csv(pd.StringIO('\n'.join(lines[daily_start:daily_end])))
daily_df['date'] = pd.to_datetime(daily_df['date'])
daily_df.plot(x='date', y='savings_pct', kind='line')

GitHub Actions (weekly stats):

yaml

on:
  schedule:
    - cron: '0 0 * * 1'
jobs:
  stats:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: cargo install rtk
      - run: rtk gain --weekly --format json > stats/week-$(date +%Y-%W).json
      - run: git add stats/ && git commit -m "Weekly rtk stats" && git push

Quota estimate

--quota estimates how many tokens RTK has saved relative to your monthly subscription budget, so you can see the cost impact of those savings.

bash

rtk gain --quota          # uses 20x tier by default
rtk gain --quota -t pro   # Claude Pro plan budget
rtk gain --quota -t 5x    # 5× usage plan budget
rtk gain --quota -t 20x   # 20× usage plan budget

The tiers (pro, 5x, 20x) correspond to Anthropic Claude API subscription levels, each with a different monthly token allocation. RTK uses those allocations as a denominator to express your savings as a percentage of your budget.

:::tip[Find missed savings] rtk gain shows what RTK saved. To find commands that ran without RTK and calculate what you lost, see rtk discover. :::

Troubleshooting

No data showing:

bash

ls -lh ~/.local/share/rtk/history.db
sqlite3 ~/.local/share/rtk/history.db "SELECT COUNT(*) FROM commands"
git status    # run any tracked command to generate data

Incorrect statistics: Token estimation is a heuristic. For precise counts, use tiktoken:

bash

pip install tiktoken
git status > output.txt
python -c "
import tiktoken
enc = tiktoken.get_encoding('cl100k_base')
print(len(enc.encode(open('output.txt').read())), 'actual tokens')
"