> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/rtk-ai/rtk/llms.txt
> Use this file to discover all available pages before exploring further.

# Token Savings

> How RTK reduces LLM token consumption by 60-90%

RTK saves **60-90% of tokens** on common development operations by filtering command output before it reaches your LLM. This translates to lower costs, faster responses, and fewer context limit issues.

## 30-Minute Claude Code Session Breakdown

> [!NOTE]
>
> **Real-world savings:** A typical 30-minute coding session uses \~150,000 tokens without RTK. With RTK, this drops to \~45,000 tokens—a **70% reduction**.

\| Operation | Frequency | Standard | rtk | Savings |
\|-----------|-----------|----------|-----|---------||
\| `ls` / `tree` | 10× | 2,000 | 400 | -80% |
\| `cat` / `read` | 20× | 40,000 | 12,000 | -70% |
\| `grep` / `rg` | 8× | 16,000 | 3,200 | -80% |
\| `git status` | 10× | 3,000 | 600 | -80% |
\| `git diff` | 5× | 10,000 | 2,500 | -75% |
\| `git log` | 5× | 2,500 | 500 | -80% |
\| `git add/commit/push` | 8× | 1,600 | 120 | -92% |
\| `npm test` / `cargo test` | 5× | 25,000 | 2,500 | -90% |
\| `ruff check` | 3× | 3,000 | 600 | -80% |
\| `pytest` | 4× | 8,000 | 800 | -90% |
\| `go test` | 3× | 6,000 | 600 | -90% |
\| `docker ps` | 3× | 900 | 180 | -80% |
\| **Total** | | **\~118,000** | **\~23,900** | **-80%** |

> [!NOTE]
>
> Estimates based on medium-sized TypeScript/Rust projects. Actual savings vary by project size and command usage patterns.

## Real Examples: Before & After

### Directory Listing

> **Standard ls -la (45 lines, \~800 tokens)**
>
> ```bash theme={null}
> drwxr-xr-x  15 user  staff    480 Jan 23 10:00 .
> drwxr-xr-x   5 user  staff    160 Jan 23 09:00 ..
> -rw-r--r--   1 user  staff   1234 Jan 23 10:00 Cargo.toml
> -rw-r--r--   1 user  staff   5678 Jan 23 10:00 Cargo.lock
> drwxr-xr-x   8 user  staff    256 Jan 23 10:00 src
> drwxr-xr-x   3 user  staff     96 Jan 23 10:00 tests
> -rw-r--r--   1 user  staff   2345 Jan 23 10:00 README.md
> -rw-r--r--   1 user  staff    567 Jan 23 10:00 .gitignore
> -rw-r--r--   1 user  staff    123 Jan 23 10:00 LICENSE
> ...
> ```

> **RTK ls (12 lines, \~150 tokens)**
>
> ```bash theme={null}
> 📁 my-project/
> ├── src/ (8 files)
> │   ├── main.rs
> │   ├── lib.rs
> │   └── filter.rs
> ├── tests/ (3 files)
> ├── Cargo.toml
> ├── Cargo.lock
> ├── README.md
> └── .gitignore
> ```
>
> **Token savings: 81%** (650 tokens saved)

### Git Operations

> **Standard git push (15 lines, \~200 tokens)**
>
> ```bash theme={null}
> Enumerating objects: 5, done.
> Counting objects: 100% (5/5), done.
> Delta compression using up to 8 threads
> Compressing objects: 100% (3/3), done.
> Writing objects: 100% (3/3), 342 bytes | 342.00 KiB/s, done.
> Total 3 (delta 2), reused 0 (delta 0)
> remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
> To github.com:user/repo.git
>    abc1234..def5678  main -> main
> ```

> **RTK git push (1 line, \~10 tokens)**
>
> ```bash theme={null}
> ok ✓ main
> ```
>
> **Token savings: 95%** (190 tokens saved)

### Test Output

> **Standard cargo test (200+ lines on failure)**
>
> ```bash theme={null}
> Compiling my-project v0.1.0 (/Users/user/my-project)
>     Finished test [unoptimized + debuginfo] target(s) in 2.34s
>      Running unittests src/lib.rs (target/debug/deps/my_project-abc123)
>
> running 15 tests
> test utils::test_parse ... ok
> test utils::test_format ... ok
> test utils::test_validate ... ok
> test core::test_init ... ok
> test core::test_process ... ok
> test core::test_filter ... ok
> test filters::test_minimal ... ok
> test filters::test_aggressive ... ok
> test tracking::test_insert ... ok
> test tracking::test_query ... ok
> test git::test_status ... ok
> test git::test_diff ... ok
> test git::test_log ... FAILED
> test runner::test_execute ... FAILED
> test runner::test_fallback ... ok
>
> failures:
>
> ---- git::test_log stdout ----
> thread 'git::test_log' panicked at 'assertion failed: `(left == right)`
>   left: `"5 commits"`,
>  right: `"3 commits"`', src/git.rs:42:5
> note: run with `RUST_BACKTRACE=1` for a backtrace
>
> ---- runner::test_execute stdout ----
> thread 'runner::test_execute' panicked at 'Expected exit code 0, got 1', src/runner.rs:18:5
>
> failures:
>     git::test_log
>     runner::test_execute
>
> test result: FAILED. 13 passed; 2 failed; 0 ignored; 0 measured; 0 filtered out
> ```

> **RTK test cargo test (\~20 lines)**
>
> ```bash theme={null}
> FAILED: 2/15 tests
>   ✗ git::test_log: assertion failed at src/git.rs:42
>      Expected: "3 commits", Got: "5 commits"
>   ✗ runner::test_execute: Expected exit code 0, got 1 at src/runner.rs:18
> ```
>
> **Token savings: 90%** (180+ lines hidden)

### Git Status

> **Standard git status (\~50 lines, \~800 tokens)**
>
> ```bash theme={null}
> On branch feature/token-optimization
> Your branch is up to date with 'origin/feature/token-optimization'.
>
> Changes not staged for commit:
>   (use "git add <file>..." to update what will be committed)
>   (use "git restore <file>..." to discard changes in working directory)
> 	modified:   src/filter.rs
> 	modified:   src/git.rs
> 	modified:   src/tracking.rs
>
> Untracked files:
>   (use "git add <file>..." to include in what will be committed)
> 	src/discover/
>
> no changes added to commit (use "git add" and/or "git commit -a")
> ```

> **RTK git status (1 line, \~20 tokens)**
>
> ```bash theme={null}
> 3 modified, 1 untracked ✓
> ```
>
> **Token savings: 97%** (780 tokens saved)

## Why Token Reduction Matters

> **Lower Costs**
>
> With Claude Sonnet 4.0 at $3/MTok input, saving 100K tokens per day = **$300/month savings\*\*.

> **Faster Responses**
>
> Smaller context = faster LLM processing. RTK reduces latency by 20-40% on large commands.

> **Context Limits**
>
> Claude has a 200K token context window. RTK helps you stay under the limit on complex projects.

> **Better Focus**
>
> LLMs perform better with concise, relevant context. RTK removes noise and highlights failures.

## Token Savings by Command Type

### File Operations (50-80% savings)

| Command | Strategy | Savings | Example |
| - | - | - | - |
| `rtk ls` | Tree compression | 50-70% | Aggregate dirs with counts |
| `rtk read` | Code filtering | 40-90% | Strip comments/bodies |
| `rtk grep` | Grouping by file | 60-80% | Truncate long lines |
| `rtk find` | Tree hierarchy | 50-70% | Compact paths |

### Git Operations (75-92% savings)

| Command | Strategy | Savings | Example |
| - | - | - | - |
| `rtk git status` | Stats extraction | 80% | "3 modified, 1 untracked" |
| `rtk git diff` | Stats + compact | 75% | "+142/-89, 3 files" |
| `rtk git log` | One-line summaries | 80% | "5 commits, +142/-89" |
| `rtk git push` | Ultra-compact | 92% | "ok ✓ main" |

### Testing (90-99% savings)

| Command | Strategy | Savings | Example |
| - | - | - | - |
| `rtk test` | Failures only | 90% | Hide passing tests |
| `rtk vitest` | ANSI stripping | 99.5% | Show only failures |
| `rtk pytest` | State machine | 90% | Parse test outcomes |
| `rtk playwright` | Failure focus | 94% | Group by suite |

### Linting (80-85% savings)

| Command | Strategy | Savings | Example |
| - | - | - | - |
| `rtk lint` | Group by rule | 84% | "no-unused-vars: 23" |
| `rtk tsc` | Group by file | 83% | "errors.ts: 5 errors" |
| `rtk ruff` | JSON parsing | 80% | Rule-based grouping |
| `rtk golangci-lint` | JSON parsing | 85% | Rule-based grouping |

## Measuring Your Savings

RTK tracks all token savings automatically in SQLite (`~/.local/share/rtk/history.db`).

### View Summary Stats

```bash theme={null}
rtk gain
```

> **Example output**
>
> ```
> 📊 RTK Token Savings
> ════════════════════════════════════════
>
> Total commands:    133
> Input tokens:      30.5K
> Output tokens:     10.7K
> Tokens saved:      25.3K (83.0%)
>
> By Command:
> ────────────────────────────────────────
> Command               Count      Saved     Avg%
> rtk git status           41      17.4K    82.9%
> rtk git push             54       3.4K    91.6%
> rtk grep                 15       3.2K    26.5%
> rtk ls                   23       1.4K    37.2%
> ```

### View Daily Breakdown

```bash theme={null}
rtk gain --daily
```

> **Example output**
>
> ```
> Daily Savings (last 30 days):
> ────────────────────────────────────────
> 01-23 │███████████████████                      6.4K
> 01-24 │██████████████████                       5.9K
> 01-25 │                                         18
> 01-26 │████████████████████████████████████████ 13.0K
> ```

### Export to CSV/JSON

```bash theme={null}
rtk gain --all --format csv > savings.csv
rtk gain --all --format json > savings.json
```

## Cost Analysis Example

**Scenario:** Mid-size TypeScript project, 8 hours/day coding with Claude Code

### Without RTK

* Commands per day: \~500
* Avg tokens per command: \~300
* Daily token usage: **150K tokens**
* Monthly usage: **3.3M tokens**
* Monthly cost (Claude Sonnet 4.0 @ $3/MTok): **$9.90\*\*

### With RTK

* Commands per day: \~500
* Avg tokens per command: \~60 (80% reduction)
* Daily token usage: **30K tokens**
* Monthly usage: **660K tokens**
* Monthly cost: **\$1.98**
* **Monthly savings: \$7.92 (80%)**

> [!NOTE]
>
> **Scales with usage:** Teams with 10 developers save **\~$80/month**. Enterprise teams (100+ devs) can save **$800+/month**.

## Token Estimation Formula

RTK uses a simple heuristic for token estimation:

```rust theme={null}
fn estimate_tokens(text: &str) -> usize {
    (text.len() as f64 / 4.0).ceil() as usize
}
```

**Approximation:** \~4 characters per token (GPT-style tokenization)

This is a rough estimate but accurate enough for tracking purposes. Real tokenization varies by model (Claude uses a different tokenizer than GPT), but the 4:1 ratio is a good average.

## Filter Effectiveness

Not all filters save the same percentage. Here's how effectiveness varies:

> **High Effectiveness**
>
> **90-99% savings**
>
> * Test output (failures only)
> * Git operations (push/pull)
> * Package managers (install)

> **Medium Effectiveness**
>
> **70-85% savings**
>
> * Linting (grouped errors)
> * Git diffs (stats mode)
> * Directory listings

> **Low Effectiveness**
>
> **40-60% savings**
>
> * Code reading (minimal filter)
> * Log files (deduplication)
> * JSON inspection

## Best Practices for Maximum Savings

**1. Use the hook**

Install `rtk init -g` for 100% adoption. Manual prefixing leads to \~60-70% adoption.

**2. Prefer rtk for repetitive commands**

Commands you run 10+ times per session (git status, test, lint) benefit most.

**3. Use aggressive filter for code reading**

`rtk read file.rs -l aggressive` strips function bodies, saving 60-90% on large files.

**4. Let failures surface naturally**

Don't use `-v` flags unless debugging. Compact output is optimized for LLMs.

**5. Review savings monthly**

Run `rtk gain --monthly` to track trends and identify optimization opportunities.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.