Architecture

┌────────────────────────────────────────────────────────────┐
│              rtk - Token Optimization Proxy                │
└────────────────────────────────────────────────────────────┘

User Input       CLI Layer        Router        Module Layer
──────────       ─────────        ──────        ────────────

$ rtk git log  ─→ Clap Parser ─→ Commands ─→  git::run()
  -v --oneline    (main.rs)      enum match
                  • Parse args                  Execute: git log
                  • Extract flags               Capture output
                  • Route command                     ↓
                                                Filter/Compress
                                                      ↓
$ 3 commits   ←─ Terminal    ←─ Format    ←─ Compact Stats
  +142/-89       colored         optimized    (90% reduction)
                 output                             ↓
                                              tracking::track()
                                                      ↓
                                              SQLite INSERT

# No flags: Compact output only
rtk git log

# -v (Level 1): Show debug messages
rtk git log -v
# Output: "Git log summary:"

# -vv (Level 2): Show command being executed
rtk git log -vv
# Output: "Executing: git log"

# -vvv (Level 3): Show raw output before filtering
rtk git log -vvv
# Output: Full unfiltered git log

// src/example_cmd.rs

use anyhow::{Context, Result};
use std::process::Command;
use crate::{tracking, utils};

/// Public entry point called by main.rs router
pub fn run(args: &[String], verbose: u8) -> Result<()> {
    // 1. Execute underlying command
    let raw_output = execute_command(args)?;

    // 2. Apply filtering strategy
    let filtered = filter_output(&raw_output, verbose);

    // 3. Print result
    println!("{}", filtered);

    // 4. Track token savings
    tracking::track(
        "original_command",
        "rtk command",
        &raw_output,
        &filtered
    );

    Ok(())
}

fn execute_command(args: &[String]) -> Result<String> {
    let output = Command::new("tool")
        .args(args)
        .output()
        .context("Failed to execute tool")?;

    // Preserve exit codes (critical for CI/CD)
    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr);
        eprintln!("{}", stderr);
        std::process::exit(output.status.code().unwrap_or(1));
    }

    Ok(String::from_utf8_lossy(&output.stdout).to_string())
}

fn filter_output(raw: &str, verbose: u8) -> String {
    // Apply filtering strategy
    // See "Filtering Strategies" section below
}

Raw: 5000 lines → Count/aggregate → "3 files, +142/-89"

stdout+stderr Mixed → stderr only → "Error: X failed"

100 errors scattered → Group by rule → "no-unused-vars: 23"
                                        "semi: 45"

Repeated log lines → Unique + count → "[ERROR] ... (×5)"

JSON with large values → Keys + types → {user: {...}, ...}

Source code → Filter by level:
  • none       → Keep all               (0%)
  • minimal    → Strip comments         (20-40%)
  • aggressive → Strip bodies           (60-90%)

100 tests mixed → Failures only → "2 failed:"
                                   "  • test_auth"

// Detection order: pnpm → yarn → npm
let is_pnpm = Path::new("pnpm-lock.yaml").exists();
let is_yarn = Path::new("yarn.lock").exists();

let mut cmd = if is_pnpm {
    Command::new("pnpm").arg("exec").arg("--").arg("eslint")
} else if is_yarn {
    Command::new("yarn").arg("exec").arg("--").arg("eslint")
} else {
    Command::new("npx").arg("--no-install").arg("--").arg("eslint")
};

lazy_static::lazy_static! {
    static ref PATTERN: Regex = Regex::new(r"ERROR:.*").unwrap();
}

// Compiled once at first use, reused forever
let matches: Vec<_> = PATTERN.find_iter(text).collect();

if !output.status.success() {
    let stderr = String::from_utf8_lossy(&output.stderr);
    eprintln!("{}", stderr);
    std::process::exit(output.status.code().unwrap_or(1));
}

~/.local/share/rtk/history.db

┌─────────────────────────────────────────┐
│ commands                                │
├─────────────────────────────────────────┤
│ id              INTEGER PRIMARY KEY     │
│ timestamp       TEXT NOT NULL           │
│ original_cmd    TEXT NOT NULL           │
│ rtk_cmd         TEXT NOT NULL           │
│ input_tokens    INTEGER NOT NULL        │
│ output_tokens   INTEGER NOT NULL        │
│ saved_tokens    INTEGER NOT NULL        │
│ savings_pct     REAL NOT NULL           │
│ exec_time_ms    INTEGER DEFAULT 0       │
└─────────────────────────────────────────┘

// Heuristic: ~4 characters per token (GPT-style)
fn estimate_tokens(text: &str) -> usize {
    (text.len() as f64 / 4.0).ceil() as usize
}

input_tokens  = estimate_tokens(raw_output);
output_tokens = estimate_tokens(filtered_output);
saved_tokens  = input_tokens - output_tokens;
savings_pct   = (saved / input) × 100.0;

// Runs on each INSERT
DELETE FROM commands
WHERE timestamp < datetime('now', '-90 days')

use anyhow::{Context, Result};

pub fn run(args: &[String], verbose: u8) -> Result<()> {
    let output = execute_command(args)
        .context("Failed to execute command")?;
    
    let filtered = filter_output(&output)
        .context("Failed to filter output")?;
    
    Ok(())
}