--- title: Token Savings Analytics description: Measure and analyze your RTK token savings with rtk gain sidebar: order: 1 --- # 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](./discover.md). ::: ## 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') " ```