rtk gain

Overview

Displays comprehensive statistics about RTK token savings, command usage, and efficiency metrics. Data persists in SQLite database with 90-day retention.

Syntax

rtk gain [OPTIONS]

Options

Scope Filters

-p, --project

flag

Show statistics for current project only (filters by working directory)

Display Modes

-g, --graph

flag

Show ASCII bar graph of daily savings (last 30 days)

-H, --history

flag

Show recent command history with savings percentages

-q, --quota

flag

Show monthly quota savings estimate

-t, --tier

string

default:"20x"

Subscription tier for quota calculation:

pro - Pro tier ($20/mo, ~6M tokens/month)
5x - Max 5x tier ($100/mo, ~30M tokens/month)
20x - Max 20x tier ($200/mo, ~120M tokens/month)

Time Breakdowns

-d, --daily

flag

Show detailed daily breakdown (all days with activity)

-w, --weekly

flag

Show weekly breakdown

-m, --monthly

flag

Show monthly breakdown

-a, --all

flag

Show all time breakdowns (daily + weekly + monthly)

Export Formats

-f, --format

string

default:"text"

Output format:

text - Styled terminal output with colors and charts
json - Machine-readable JSON
csv - CSV format for spreadsheet import

Diagnostics

-F, --failures

flag

Show parse failure log (commands that fell back to raw execution)

Default Output (Summary)

RTK Token Savings (Global Scope)
════════════════════════════════════════════════════════════

Total commands:    1,234
Input tokens:      2.5M
Output tokens:     450K
Tokens saved:      2.05M (82.0%)
Total exec time:   15m 30s (avg 750ms)
Efficiency meter: ████████████████████░░░░ 82.0%

By Command
────────────────────────────────────────────────────────────
 #  Command                  Count  Saved    Avg%    Time    Impact
────────────────────────────────────────────────────────────
 1. rtk cargo test             234   890K    92.1%   2.3s   ██████████
 2. rtk git status             456   650K    71.5%   450ms  ████████░░
 3. rtk tsc                     89   310K    85.2%   1.8s   ██████░░░░
 4. rtk grep                   123   105K    76.3%   120ms  ███░░░░░░░
 ...
────────────────────────────────────────────────────────────

Output with Flags

Graph (`-g`)

Daily Savings (last 30 days)
──────────────────────────────────────────────────────────
01-15 │████████████████████████░░░░░░░░░░░░░░░░ 45K
01-16 │██████████████████████████████████████░░ 62K
01-17 │████████████████████████████░░░░░░░░░░░░ 38K
...

History (`-H`)

Recent Commands
──────────────────────────────────────────────────────────
01-20 14:32 ▲ rtk cargo test            -92% (890K)
01-20 14:28 ■ rtk git status            -71% (12K)
01-20 14:15 • rtk grep "TODO"           -76% (8K)
...

Legend:

▲ - High savings (≥70%)
■ - Medium savings (30-70%)
• - Low savings (<30%)

Quota (`-q`)

Monthly Quota Analysis
──────────────────────────────────────────────────────────
Subscription tier:         Max 20x ($200/mo)
Estimated monthly quota:   120M
Tokens saved (lifetime):   2.05M
Quota preserved:           1.7%

Note: Heuristic estimate based on ~44K tokens/5h (Pro baseline)
      Actual limits use rolling 5-hour windows, not monthly caps.

Project Scope (`-p`)

RTK Token Savings (Project Scope)
════════════════════════════════════════════════════════════
Scope: /Users/dev/projects/my-app

Total commands:    156
Input tokens:      350K
Output tokens:     82K
Tokens saved:      268K (76.6%)

Failures (`-F`)

RTK Parse Failures
════════════════════════════════════════════════════════════

Total failures:      23
Recovery rate:       100.0%

Top Commands (by frequency):
────────────────────────────────────────────────────────────
    5x  git log --graph --all --decorate --oneline
    3x  find . -name "*.rs" -type f -exec grep -H ...
    2x  docker ps -a --format "table {{.Names}}\t{{...

Recent Failures (last 10):
────────────────────────────────────────────────────────────
  2026-01-20 14:45 [ok] git log --graph --all
  2026-01-20 12:30 [ok] find . -name "*.tmp" -delete

JSON Export Format

{
  "summary": {
    "total_commands": 1234,
    "total_input": 2500000,
    "total_output": 450000,
    "total_saved": 2050000,
    "avg_savings_pct": 82.0,
    "total_time_ms": 930000,
    "avg_time_ms": 753
  },
  "daily": [
    {
      "date": "2026-01-20",
      "commands": 45,
      "input_tokens": 120000,
      "output_tokens": 28000,
      "saved_tokens": 92000,
      "savings_pct": 76.7,
      "total_time_ms": 34500,
      "avg_time_ms": 767
    }
  ]
}

CSV Export Format

date,commands,input_tokens,output_tokens,saved_tokens,savings_pct,total_time_ms,avg_time_ms
2026-01-20,45,120000,28000,92000,76.67,34500,767
2026-01-19,52,135000,31000,104000,77.04,38200,735

Database Location

Default: ~/.local/share/rtk/tracking.db Customize via:

Environment variable: RTK_DB_PATH=/custom/path.db

Config file: ~/.config/rtk/config.toml

[tracking]
database_path = "/custom/path.db"

Token Savings Methodology

RTK measures savings by comparing:

Input tokens: Character count of raw command output ÷ 4
Output tokens: Character count of RTK filtered output ÷ 4
Saved tokens: Input tokens - Output tokens
Savings %: (Saved tokens ÷ Input tokens) × 100

Note: Division by 4 is a rough heuristic (Claude 3.5 Sonnet averages ~4 chars/token). Actual tokenization varies by content.

rtk gain
# Shows overall stats + top commands

Exit Codes

0 - Success (always succeeds)

rtk discover - Find missed RTK opportunities in Claude Code history
rtk config - View/edit configuration
rtk init --show - Show installation status

Command Reference

Global Flags

Overview

Syntax

Options

Scope Filters

Display Modes

Time Breakdowns

Export Formats

Diagnostics

Default Output (Summary)

Output with Flags

Graph (`-g`)

History (`-H`)

Quota (`-q`)

Project Scope (`-p`)

Failures (`-F`)

JSON Export Format

CSV Export Format

Database Location

Token Savings Methodology

Exit Codes

Build docs developers (and LLMs) love

Command Reference

Global Flags

Documentation Index

​Overview

​Syntax

​Options

​Scope Filters

​Display Modes

​Time Breakdowns

​Export Formats

​Diagnostics

​Default Output (Summary)

​Output with Flags

​Graph (-g)

​History (-H)

​Quota (-q)

​Project Scope (-p)

​Failures (-F)

​JSON Export Format

​CSV Export Format

​Database Location

​Token Savings Methodology

​Exit Codes

​Related Commands

Build docs developers (and LLMs) love

Overview

Syntax

Options

Scope Filters

Display Modes

Time Breakdowns

Export Formats

Diagnostics

Default Output (Summary)

Output with Flags

Graph (`-g`)

History (`-H`)

Quota (`-q`)

Project Scope (`-p`)

Failures (`-F`)

JSON Export Format

CSV Export Format

Database Location

Token Savings Methodology

Exit Codes

Related Commands