| title | Token Savings Analytics | ||
|---|---|---|---|
| description | Measure and analyze the bash output reduction RTK achieves with rtk gain | ||
| sidebar |
|
rtk gain shows how much bash output RTK has removed across all your commands, with daily, weekly, and monthly breakdowns.
What rtk gain measures is the reduction in bash output bytes, converted to estimated tokens. Bash output is one contributor to input tokens, alongside your prompt, the system prompt and conversation history, and input tokens are in turn only part of the bill, which also counts output tokens. See How RTK Savings Work for the full picture.
# 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
rtk gain --recalls # recall efficiency per filter (calibration)
# Export
rtk gain --all --format json > savings.json
rtk gain --all --format csv > savings.csvrtk gain --dailyExample output (illustrative numbers from one machine, not typical results — yours depend entirely on which commands you run):
📅 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 (
bytes / 4) - Output: Estimated tokens after filtering (
bytes / 4) - Saved: Input - Output, in estimated tokens
- Save%: Saved / Input × 100 — a bash output byte ratio, not a share of your bill
rtk gain --weekly
rtk gain --monthlySame columns as daily, aggregated by Sunday-Saturday week or calendar month.
| Format | Flag | Use case |
|---|---|---|
text |
default | Terminal display |
json |
--format json |
Programmatic analysis, dashboards |
csv |
--format csv |
Excel, Python/R, Google Sheets |
JSON structure:
{
"summary": {
"total_commands": 196,
"total_input": 1276098,
"total_output": 59244,
"total_saved": 1220217,
"avg_savings_pct": 95.62
},
"daily": [...],
"weekly": [...],
"monthly": [...]
}| Command | Bash output reduction | 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 |
These percentages measure bash output bytes removed, not cost reduction.
rtk gain estimates tokens as bytes / 4 (src/core/tracking.rs:1284). RTK ships no real tokenizer by design: embedding one would cost startup time and would require a tokenizer per model, or a per-session model lookup, which RTK does not implement. The same estimator is applied to raw and filtered output, so the percentage is reliable; the absolute token counts are approximate and will not match your provider's billing.
Input Tokens = estimate_tokens(raw_command_output)
Output Tokens = estimate_tokens(rtk_filtered_output)
Saved Tokens = Input - Output
Savings % = (Saved / Input) × 100
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
# 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# 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.jsonPython/pandas:
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):
on:
schedule:
- cron: '0 0 * * 1'
jobs:
stats:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- run: cargo install --git https://github.com/rtk-ai/rtk --branch master 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 expresses the estimated tokens saved as a fraction of a monthly subscription budget. Like every other figure in rtk gain, it is derived from the bytes / 4 estimate of bash output, so treat it as an order of magnitude rather than a billing forecast.
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 budgetThe 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.
:::
--recalls measures how often your AI assistant goes back for output a filter elided — the signal that a filter's cap is too aggressive for your workflow. Every time a filter stores elided output (an elision) and every time the assistant retrieves it (a recall), RTK counts it per filter:
rtk gain --recallsRecall efficiency (current mode: sqlite)
SQLITE (exact — reads go through rtk recall)
FILTER ELISIONS RECALLED RATE
vitest 67 29 43%
docker-images 142 3 2%
TEE (approximate — bash-observed reads only)
FILTER ELISIONS RECALLED RATE
cargo_test 38 4 ≥10%
How to read it:
- RATE is the share of elided outputs the assistant went back for. Re-reading the same entry counts once — the rate measures entries consulted, not read commands.
- A high rate (say above 30%) means that filter regularly hides output the assistant needs: every recall is an extra API round-trip you paid for. Consider raising that filter's cap.
- A low rate means the filter's cap is well calibrated — the elided output was noise.
The two sections are never merged because the data quality differs:
- SQLITE (exact): reads go through
rtk recall <hash>, the only access path, so the count is exact. - TEE (approximate): in legacy tee mode, reads are shell commands (
tail,cat,grep, …) observed by the rewrite hook before execution. Editor or assistant file-tool reads are invisible, denied commands are not counted, and the per-file dedup window is finite — so the≥rate is approximate, not exact. A high rate is still a reliable signal that the cap is too aggressive.
Stats survive entry eviction and retention cleanup: calibration data is kept even after the underlying outputs are purged.
No data showing:
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 dataIncorrect statistics: Token estimation is a heuristic. For precise counts, use tiktoken:
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')
"