From 4dc380efd27432220ec95560cf56174d22aea8d4 Mon Sep 17 00:00:00 2001
From: Florian BRUNIAUX <florian@bruniaux.com>
Date: Wed, 28 Jan 2026 12:20:48 +0100
Subject: [PATCH] docs: integrate RTK (Rust Token Killer) for command output
 optimization

- Added Section 9.13 'Command Output Optimization with RTK' (guide/ultimate-guide.md:10478)
- Benchmarks: 72.6% avg token reduction (git log 92.3%, git status 76.0%, find 76.3%)
- Integration templates: CLAUDE.md, Skill, PreToolUse hook
- Evaluation: docs/resource-evaluations/rtk-evaluation.md (score 4/5)
- Limitations: grep broken (v0.2.0), ls worse (-274%), low adoption (8 stars)
- Updated CHANGELOG.md and machine-readable/reference.yaml
- Source: https://github.com/pszymkowiak/rtk v0.2.0
---
 CHANGELOG.md                    | 20 +++++++
 guide/ultimate-guide.md         | 92 +++++++++++++++++++++++++++++++++
 machine-readable/reference.yaml | 13 +++++
 3 files changed, 125 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9b38791..4e009e2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
   - **Verified patterns now documented**: hookify, pass@k metrics, sandboxed subagents, strategic compaction skills
   - **Impact**: Maintains guide credibility, prevents user confusion, ensures accuracy of ecosystem documentation
 
+### Added
+
+- **RTK (Rust Token Killer) integration** — Command output optimization tool for 72.6% token reduction
+  - **New documentation**: `docs/resource-evaluations/rtk-evaluation.md` (comprehensive evaluation, score 4/5)
+  - **Guide integration**: Section 9.13 Cost Optimization → new "Command Output Optimization with RTK" subsection
+  - **Benchmarks verified**:
+    - `rtk git log`: 92.3% reduction (13,994 → 1,076 chars)
+    - `rtk git status`: 76.0% reduction (100 → 24 chars)
+    - `rtk find`: 76.3% reduction (780 → 185 chars)
+    - Average across working commands: 72.6% reduction
+  - **Integration templates**:
+    - `examples/claude-md/rtk-optimized.md`: CLAUDE.md template for manual RTK usage
+    - `examples/skills/rtk-optimizer/SKILL.md`: Auto-suggestion skill for high-verbosity commands
+    - `examples/hooks/bash/rtk-auto-wrapper.sh`: PreToolUse hook for automatic RTK wrapping
+  - **Upstream contributions**: `claudedocs/rtk-pr-proposals.md` with 7 PR proposals (grep fix, ls fix, npm support)
+  - **Limitations documented**: grep broken (v0.2.0), ls worse (-274%), low adoption (8 stars), early-stage
+  - **Use cases**: Git workflows, file finding, large file reading (avoid: ls, grep, small outputs)
+  - **Impact**: Proven 72.6% token reduction for git operations, validates preprocessing optimization strategy
+  - **Reference**: https://github.com/pszymkowiak/rtk
+
 ## [3.17.1] - 2026-01-27
 
 ### Added
diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md
index b416bae..a1bf1cc 100644
--- a/guide/ultimate-guide.md
+++ b/guide/ultimate-guide.md
@@ -10475,6 +10475,98 @@ You: "Fix typos in auth.ts, user.ts, and api.ts"
 # Single context load, multiple fixes
 ```
 
+### Command Output Optimization with RTK
+
+**RTK (Rust Token Killer)** filters bash command outputs **before** they reach Claude's context, achieving 72.6% average token reduction for git workflows.
+
+**Installation:**
+
+```bash
+# macOS ARM64 (Apple Silicon)
+curl -fsSL "https://github.com/pszymkowiak/rtk/releases/latest/download/rtk-aarch64-apple-darwin.tar.gz" -o rtk.tar.gz && tar -xzf rtk.tar.gz && sudo mv rtk /usr/local/bin/ && rm rtk.tar.gz
+
+# macOS Intel
+curl -fsSL "https://github.com/pszymkowiak/rtk/releases/latest/download/rtk-x86_64-apple-darwin.tar.gz" -o rtk.tar.gz && tar -xzf rtk.tar.gz && sudo mv rtk /usr/local/bin/ && rm rtk.tar.gz
+
+# Verify installation
+rtk --version  # Should output: rtk 0.2.0
+```
+
+**Proven Token Savings (Benchmarked):**
+
+| Command | Baseline | RTK | Reduction |
+|---------|----------|-----|-----------|
+| `rtk git log` | 13,994 chars | 1,076 chars | **92.3%** |
+| `rtk git status` | 100 chars | 24 chars | **76.0%** |
+| `rtk find "*.md"` | 780 chars | 185 chars | **76.3%** |
+| `rtk git diff` | 15,815 chars | 6,982 chars | **55.9%** |
+| `cat CHANGELOG.md` | 163,587 chars | 61,339 chars | **62.5%** |
+
+**Average: 72.6% token reduction**
+
+**Usage Pattern:**
+
+```bash
+# Instead of:
+git log --oneline
+git status
+git diff HEAD~1
+
+# Use:
+rtk git log
+rtk git status
+rtk git diff HEAD~1
+```
+
+**Real-World Impact:**
+
+```
+30-minute Claude Code session:
+- Without RTK: ~150K tokens (10-15 git commands @ ~10K tokens each)
+- With RTK: ~41K tokens (10-15 git commands @ ~2.7K tokens each)
+- Savings: 109K tokens (72.6% reduction)
+```
+
+**Integration Strategies:**
+
+1. **CLAUDE.md instruction** (manual wrapper):
+   ```markdown
+   ## Token Optimization
+
+   Use RTK for git operations:
+   - `rtk git log` (92.3% reduction)
+   - `rtk git status` (76.0% reduction)
+   - `rtk git diff` (55.9% reduction)
+   ```
+
+2. **Skill** (auto-suggestion):
+   - Template: `examples/skills/rtk-optimizer/SKILL.md`
+   - Detects high-verbosity commands
+   - Suggests RTK wrapper automatically
+
+3. **Hook** (automatic wrapper):
+   - Template: `examples/hooks/bash/rtk-auto-wrapper.sh`
+   - PreToolUse hook intercepts bash commands
+   - Applies RTK wrapper when beneficial
+
+**Limitations (v0.2.0):**
+
+- ❌ `grep` returns empty output (bug)
+- ❌ `ls` produces **worse** output (-274% token increase)
+- ⚠️ Early-stage project (8 GitHub stars, may be abandoned)
+- ⚠️ npm/pnpm/yarn not supported yet
+
+**Recommendation:**
+
+- ✅ Use for: git workflows, file finding, large file reading
+- ❌ Skip for: ls, grep, small outputs, quick exploration
+
+**See also:**
+
+- Evaluation: `docs/resource-evaluations/rtk-evaluation.md`
+- Templates: `examples/{claude-md,skills,hooks}/rtk-*`
+- GitHub: https://github.com/pszymkowiak/rtk
+
 ### Cost Tracking
 
 **Monitor cost with `/status`:**
diff --git a/machine-readable/reference.yaml b/machine-readable/reference.yaml
index 09c2285..c09d19b 100644
--- a/machine-readable/reference.yaml
+++ b/machine-readable/reference.yaml
@@ -31,6 +31,18 @@ deep_dive:
   bridge_script: "examples/scripts/bridge.py"
   bridge_schema: "examples/scripts/bridge-plan-schema.json"
   bridge_guide: "guide/ultimate-guide.md:14079"
+  # Cost optimization - RTK (Rust Token Killer)
+  rtk_tool: "https://github.com/pszymkowiak/rtk"
+  rtk_evaluation: "docs/resource-evaluations/rtk-evaluation.md"
+  rtk_guide: "guide/ultimate-guide.md:10478"
+  rtk_claude_md: "examples/claude-md/rtk-optimized.md"
+  rtk_skill: "examples/skills/rtk-optimizer/SKILL.md"
+  rtk_hook: "examples/hooks/bash/rtk-auto-wrapper.sh"
+  rtk_pr_proposals: "claudedocs/rtk-pr-proposals.md"
+  rtk_purpose: "Command output filtering before LLM context (72.6% avg reduction)"
+  rtk_version_tested: "v0.2.0"
+  rtk_score: "4/5"
+  rtk_installation: "Binary download (GitHub releases)"
   # PDF Generation
   pdf_generation: "guide/workflows/pdf-generation.md"
   pdf_generator_skill: "examples/skills/pdf-generator.md"
@@ -618,6 +630,7 @@ cost:
   opus: "architecture, complex bugs ($$$)"
   opusplan: "plan=opus + execute=sonnet ($$)"
   tip: "--add-dir grants tool access to additional directories (permissions, not context loading)"
+  rtk: "Command output filtering (72.6% avg reduction) - rtk git log/status/diff"
 
 # ════════════════════════════════════════════════════════════════
 # TOOL SELECTION