rtk

The Problem

Developers routinely feed large command outputs—git status, cargo test, ls, etc.—into LLM contexts, inflating token usage and cost. A single 30‑minute Claude Code session can consume ~118 k tokens; the same work filtered through rtk drops to ~24 k, an ~80 % reduction. The pain is especially acute for repetitive dev commands that generate voluminous, often noisy output.

What This Does

rtk is a single Rust binary (src/main.rs:1308) that sits between the CLI and the LLM, intercepting command execution, stripping irrelevant data, and compressing the remainder. The core pipeline runs through run_cli → run → a chain of small functions defined in src/core/filter.rs, src/core/utils.rs, and src/core/stream.rs. These modules perform token counting (format_tokens), ANSI stripping (strip_ansi), and output truncation (format_cpt).

The repository is a portfolio of four semi‑independent projects:

Over 130 code files (Rust 101, TypeScript 8, Shell 19, etc.) implement >2 600 functions and 212 classes. Token‑saving logic lives in src/discover/registry.rs (defines classify_command, extract_base_command, etc.) and src/parser/mod.rs (provides unwrap, tier, is_ok).

How It Is Wired

Execution starts at main in src/main.rs:1308, which reaches 399 functions and is called from nothing else in the repo. From there run_cli (also in src/main.rs:1319) dispatches to run (src/analytics/cc_economics.rs:182), the central analytics entry point that touches the database, runs external commands via exec_capture, and makes an outbound network call to report usage.

Key call‑graph hubs (from the measured internal call graph):

Paths that leave the process: main → run_cli → subprocess via cmd.status().context, db via core::utils::resolved_command("npx"); run → exec_capture → subprocess via cmd.output().context; run_fallback → record_parse_failure_silent → record_parse_failure → db via self.conn.execute.

The module‑responsibility map (functions called from other files) highlights the widest blast radius:

• src/discover/registry.rs – 255 functions, called from 6 files
• src/core/filter.rs – 17 functions, called from 41 files
• src/core/utils.rs – 70 functions, called from 26 files, runs external commands
• src/hooks/init.rs – 130 functions, called from 5 files
• src/cmds/dotnet/dotnet_cmd.rs – 112 functions, called from 5 files, implements run_build, run_test, etc.

How To Use It

Setup – Install via Homebrew (recommended) or cargo:

brew install rtk                         # Homebrew
# or
cargo install --git https://github.com/rtk-ai/rtk

The install script (install.sh at the repo root) places the binary in ~/.local/bin; add that directory to your shell RC if needed.

Configuration – No external keys are required; rtk uses an internal filter registry (.rtk/filters.toml) to decide which commands to compress. Environment variables such as RTK_DISABLE can suppress specific command families.

Running it – Replace the target command with rtk <cmd>. Example:

rtk git status
rtk cargo test
rtk ls -la

The binary transparently proxy‑es the command, returns a condensed token‑optimized output, and logs savings to stdout (run rtk gain for stats).

Real‑World Use

During a feature‑branch workflow a developer runs rtk git diff after editing several files. Without rtk the diff (≈10 k tokens) floods the LLM context, pushing the session past the model’s limit and incurring extra tokens. With rtk the diff is collapsed to ~2.5 k tokens (≈75 % savings), allowing the model to focus on the actual changes rather than boilerplate. The developer then pipes the result into the LLM for code‑review suggestions, and the reduced context keeps response latency low.

Code Health & Issues

Measured static‑analysis findings (70 total, 22 high, 48 medium, 0 low):

• [HIGH/cognitive_load] Deep nesting x41 – files src/cmds/cloud/aws_cmd.rs, src/cmds/cloud/container.rs, src/cmds/dotnet/dotnet_trx.rs; max indentation depth 10 makes control flow hard to follow. Fix: flatten with early returns/guard clauses.
• [HIGH/clarity] Duplicated code blocks x191 – 6‑line patterns repeated across 30 files, notably in hooks/claude/rtk-rewrite.sh, hooks/cursor/rtk-rewrite.sh, and test‑rewrite hooks. Fix: extract shared helpers; DRY the logic.
• [HIGH/cognitive_load] Oversized file x18 – src/cmds/cloud/aws_cmd.rs (2295 lines), src/cmds/dotnet/binlog.rs, src/cmds/dotnet/dotnet_cmd.rs. Fix: split into cohesive units by responsibility.

Code‑health audit (7 findings, 0 critical):

• [HIGH] Pin third‑party GitHub Actions to commit SHAs – .github/workflows uses @vN tags that can move, risking secret exposure. Fix: replace each @vN with the 40‑char SHA; let Dependabot bump SHAs.
• [HIGH] Add a test suite – 111 source files have no tests; any change ships with no regression signal. Fix: add one test per public entry point and a CI step to run them.
• [MEDIUM] Declare least‑privilege permissions for GITHUB_TOKEN – pr-target-check.yml has no permissions declaration, so the token inherits repo defaults. Fix: add permissions: contents: read at the top and widen per‑job only where needed.
• [MEDIUM] Enable Dependabot or Renovate – two manifest files exist but no update bot is configured. Fix: commit .github/dependabot.yml covering Rust, Node, and GitHub Actions.
• [MEDIUM] Set persist-credentials: false on checkout – ci.yml keeps the token for all later steps, allowing a malicious post‑install script to read pushable credentials. Fix: add with: persist-credentials: false and pass an explicit token only to the push step.
• [LOW] Set timeout-minutes on workflow jobs – four jobs have no timeout, risking overlap on a two‑hourly schedule. Fix: add a realistic timeout-minutes to each job.
• [LOW] Add convention files – missing .editorconfig, .gitattributes, formatter config. Fix: add those files with appropriate settings.

The Bottom Line

rtk delivers a measurable 60‑90 % token reduction for common dev commands with <10 ms overhead, making it a practical drop‑in proxy for any LLM‑augmented workflow. The codebase shows clear hotspots—deep nesting, duplicated shells, and outsized files—that should be refactored to lower cognitive load and improve maintainability. Teams that frequently feed CLI output into LLMs (e.g., code‑review bots, automated documentation generators) will see immediate cost and latency benefits, provided they address the identified structural debt.