RTK Token Savings Audit Guide

Complete guide to analyzing your rtk token savings with temporal breakdowns and data exports.

Overview

The rtk gain command provides comprehensive analytics for tracking your token savings across time periods.

Database Location: ~/.local/share/rtk/history.db Retention Policy: 90 days Scope: Global across all projects, worktrees, and Claude sessions

Quick Reference

# Default summary view
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            # Show all breakdowns at once

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

# Combined flags
rtk gain --graph --history --quota    # Classic view with extras
rtk gain --daily --weekly --monthly   # Multiple breakdowns

Command Options

Temporal Flags

Flag	Description	Output
`--daily`	Day-by-day breakdown	All days with full metrics
`--weekly`	Week-by-week breakdown	Aggregated by Sunday-Saturday weeks
`--monthly`	Month-by-month breakdown	Aggregated by calendar month
`--all`	All time breakdowns	Daily + Weekly + Monthly combined

Classic Flags (still available)

Flag	Description
`--graph`	ASCII graph of last 30 days
`--history`	Recent 10 commands
`--quota`	Monthly quota analysis (Pro/5x/20x tiers)
`--tier <TIER>`	Quota tier: pro, 5x, 20x (default: 20x)

Export Formats

Format	Flag	Use Case
`text`	`--format text` (default)	Terminal display
`json`	`--format json`	Programmatic analysis, APIs
`csv`	`--format csv`	Excel, data analysis, plotting

Output Examples

Daily Breakdown

📅 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%

Metrics explained:

Cmds: Number of rtk commands executed
Input: Estimated tokens from raw command output
Output: Actual tokens after rtk filtering
Saved: Input - Output (tokens prevented from reaching LLM)
Save%: Percentage reduction (Saved / Input × 100)

Weekly Breakdown

📊 Weekly Breakdown (1 weeks)
════════════════════════════════════════════════════════════════════════
Week                      Cmds      Input     Output      Saved   Save%
────────────────────────────────────────────────────────────────────────
01-26 → 02-01              196       1.3M      59.2K       1.2M   95.6%
────────────────────────────────────────────────────────────────────────
TOTAL                      196       1.3M      59.2K       1.2M   95.6%

Week definition: Sunday to Saturday (ISO week starting Sunday at 00:00)

Monthly Breakdown

📆 Monthly Breakdown (1 months)
════════════════════════════════════════════════════════════════
Month         Cmds      Input     Output      Saved   Save%
────────────────────────────────────────────────────────────────
2026-01        196       1.3M      59.2K       1.2M   95.6%
────────────────────────────────────────────────────────────────
TOTAL          196       1.3M      59.2K       1.2M   95.6%

Month format: YYYY-MM (calendar month)

JSON Export

{
  "summary": {
    "total_commands": 196,
    "total_input": 1276098,
    "total_output": 59244,
    "total_saved": 1220217,
    "avg_savings_pct": 95.62
  },
  "daily": [
    {
      "date": "2026-01-28",
      "commands": 89,
      "input_tokens": 380894,
      "output_tokens": 26744,
      "saved_tokens": 355779,
      "savings_pct": 93.41
    }
  ],
  "weekly": [...],
  "monthly": [...]
}

Use cases:

API integration
Custom dashboards
Automated reporting
Data pipeline ingestion

CSV Export

# Daily Data
date,commands,input_tokens,output_tokens,saved_tokens,savings_pct
2026-01-28,89,380894,26744,355779,93.41
2026-01-29,102,894455,32445,863744,96.57

# Weekly Data
week_start,week_end,commands,input_tokens,output_tokens,saved_tokens,savings_pct
2026-01-26,2026-02-01,196,1276098,59244,1220217,95.62

# Monthly Data
month,commands,input_tokens,output_tokens,saved_tokens,savings_pct
2026-01,196,1276098,59244,1220217,95.62

Use cases:

Excel analysis
Python/R data science
Google Sheets dashboards
Matplotlib/seaborn plotting

Analysis Workflows

Weekly Progress Tracking

# Generate weekly report every Monday
rtk gain --weekly --format csv > reports/week-$(date +%Y-%W).csv

# Compare this week vs last week
rtk gain --weekly | tail -3

Monthly Cost Analysis

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

Data Science Analysis

import pandas as pd
import subprocess

# Get CSV data
result = subprocess.run(['rtk', 'gain', '--all', '--format', 'csv'],
                       capture_output=True, text=True)

# Parse daily data
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])))

# Plot savings trend
daily_df['date'] = pd.to_datetime(daily_df['date'])
daily_df.plot(x='date', y='savings_pct', kind='line')

Excel Analysis

Export CSV: rtk gain --all --format csv > rtk-data.csv
Open in Excel
Create pivot tables:
- Daily trends (line chart)
- Weekly totals (bar chart)
- Savings % distribution (histogram)

Dashboard Creation

# Generate dashboard data daily via cron
0 0 * * * rtk gain --all --format json > /var/www/dashboard/rtk-stats.json

# Serve with static site
cat > index.html <<'EOF'
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<canvas id="savings"></canvas>
<script>
fetch('rtk-stats.json')
  .then(r => r.json())
  .then(data => {
    new Chart(document.getElementById('savings'), {
      type: 'line',
      data: {
        labels: data.daily.map(d => d.date),
        datasets: [{
          label: 'Daily Savings %',
          data: data.daily.map(d => d.savings_pct)
        }]
      }
    });
  });
</script>
EOF

Understanding Token Savings

Token Estimation

rtk estimates tokens using text.len() / 4 (4 characters per token average).

Accuracy: ±10% compared to actual LLM tokenization (sufficient for trends).

Savings Calculation

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

Typical Savings by Command

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

Database Management

Inspect Raw Data

# Location
ls -lh ~/.local/share/rtk/history.db

# Schema
sqlite3 ~/.local/share/rtk/history.db ".schema"

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

# Total database size
sqlite3 ~/.local/share/rtk/history.db \
  "SELECT COUNT(*),
          SUM(saved_tokens) as total_saved,
          MIN(DATE(timestamp)) as first_record,
          MAX(DATE(timestamp)) as last_record
   FROM commands"

Backup & Restore

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

# Restore
cp ~/backups/rtk-history-20260128.db ~/.local/share/rtk/history.db

# Export for migration
sqlite3 ~/.local/share/rtk/history.db .dump > rtk-backup.sql

Cleanup

# Manual cleanup (older than 90 days)
sqlite3 ~/.local/share/rtk/history.db \
  "DELETE FROM commands WHERE timestamp < datetime('now', '-90 days')"

# Reset all data
rm ~/.local/share/rtk/history.db
# Next rtk command will recreate database

Integration Examples

GitHub Actions CI/CD

# .github/workflows/rtk-stats.yml
name: RTK Stats Report
on:
  schedule:
    - cron: '0 0 * * 1'  # Weekly on Monday
jobs:
  stats:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install rtk
        run: cargo install --path .
      - name: Generate report
        run: |
          rtk gain --weekly --format json > stats/week-$(date +%Y-%W).json
      - name: Commit stats
        run: |
          git add stats/
          git commit -m "Weekly rtk stats"
          git push

Slack Bot

import subprocess
import json
import requests

def send_rtk_stats():
    result = subprocess.run(['rtk', 'gain', '--format', 'json'],
                           capture_output=True, text=True)
    data = json.loads(result.stdout)

    message = f"""
    📊 *RTK Token Savings Report*

    Total Saved: {data['summary']['total_saved']:,} tokens
    Savings Rate: {data['summary']['avg_savings_pct']:.1f}%
    Commands: {data['summary']['total_commands']}
    """

    requests.post(SLACK_WEBHOOK_URL, json={'text': message})

Troubleshooting

No data showing

# Check if database exists
ls -lh ~/.local/share/rtk/history.db

# Check record count
sqlite3 ~/.local/share/rtk/history.db "SELECT COUNT(*) FROM commands"

# Run a tracked command to generate data
rtk git status

Export fails

# Check for pipe errors
rtk gain --format json 2>&1 | tee /tmp/rtk-debug.log | jq .

# Use release build to avoid warnings
cargo build --release
./target/release/rtk gain --format json

Incorrect statistics

Token estimation is a heuristic. For precise measurements:

# Install tiktoken
pip install tiktoken

# Validate estimation
rtk git status > output.txt
python -c "
import tiktoken
enc = tiktoken.get_encoding('cl100k_base')
text = open('output.txt').read()
print(f'Actual tokens: {len(enc.encode(text))}')
print(f'rtk estimate: {len(text) // 4}')
"

Best Practices

Regular Exports: rtk gain --all --format json > monthly-$(date +%Y%m).json
Trend Analysis: Compare week-over-week savings to identify optimization opportunities
Command Profiling: Use --history to see which commands save the most
Backup Before Cleanup: Always backup before manual database operations
CI Integration: Track savings across team in shared dashboards

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RTK Token Savings Audit Guide

Overview

Quick Reference

Command Options

Temporal Flags

Classic Flags (still available)

Export Formats

Output Examples

Daily Breakdown

Weekly Breakdown

Monthly Breakdown

JSON Export

CSV Export

Analysis Workflows

Weekly Progress Tracking

Monthly Cost Analysis

Data Science Analysis

Excel Analysis

Dashboard Creation

Understanding Token Savings

Token Estimation

Savings Calculation

Typical Savings by Command

Database Management

Inspect Raw Data

Backup & Restore

Cleanup

Integration Examples

GitHub Actions CI/CD

Slack Bot

Troubleshooting

No data showing

Export fails

Incorrect statistics

Best Practices

See Also

FilesExpand file tree

AUDIT_GUIDE.md

Latest commit

History

AUDIT_GUIDE.md

File metadata and controls

RTK Token Savings Audit Guide

Overview

Quick Reference

Command Options

Temporal Flags

Classic Flags (still available)

Export Formats

Output Examples

Daily Breakdown

Weekly Breakdown

Monthly Breakdown

JSON Export

CSV Export

Analysis Workflows

Weekly Progress Tracking

Monthly Cost Analysis

Data Science Analysis

Excel Analysis

Dashboard Creation

Understanding Token Savings

Token Estimation

Savings Calculation

Typical Savings by Command

Database Management

Inspect Raw Data

Backup & Restore

Cleanup

Integration Examples

GitHub Actions CI/CD

Slack Bot

Troubleshooting

No data showing

Export fails

Incorrect statistics

Best Practices

See Also