Hermes Wiki
Tools/RTK

RTK — Rust Token Killer

Single-binary Rust CLI proxy that sits between your AI coding agent and the shell. Intercepts dev commands (git, cargo, pytest, docker, aws, kubectl, etc.), runs the real command, and rewrites raw output into a compressed, LLM-friendly form before it reaches the agent's context window.

Claims 60–90% token savings on common dev-loop commands with <10ms overhead.

[!note] Harness-layer optimization Zero model changes, zero prompt changes — pure I/O shaping at the tool-call boundary. Evidence for "harness engineering > model engineering."

How It Works

Mental model: A compiler for shell output — same way gzip doesn't change what data means, RTK doesn't change what git status tells you, just how many tokens it costs to tell an LLM.

RTK installs as:

  • PreToolUse hook for Claude Code, Cursor, Copilot, Gemini CLI
  • Native plugin for Hermes, OpenCode, OpenClaw
  • Rules file for Windsurf, Cline, Kilo Code

When the agent issues git status, the hook silently rewrites it to rtk git status. The agent never knows.

Four Compression Strategies

  1. Smart filtering — strip comments, whitespace, boilerplate
  2. Grouping — aggregate similar items (files by directory, errors by type)
  3. Truncation — keep relevant context, cut redundancy
  4. Deduplication — collapse repeated log lines with counts

On failure, RTK tee-logs the full output locally (~/.local/share/rtk/tee/) — so the agent can pull complete detail on demand. Compression ≠ information loss; it means info is fetched on demand instead of pushed by default.

Real Numbers (LangGraph + Qwen2.5:7b)

Command Raw tokens RTK tokens Savings
git log --stat -2 8,388 108 98.7%
git branch -v 88 6 93.2%
git status 66 22 66.7%
ls -la 376 113 69.9%
Agent session total 8,592 231 97.3%

Same quality response from the model. 97.3% fewer context tokens.

Quickstart

# macOS
brew install rtk

# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

rtk --version
rtk init -g           # installs hook for Claude Code
# restart Claude Code — git status now transparently becomes rtk git status

Hermes Plugin

rtk init --agent hermes
# places files under ~/.hermes/plugins/rtk-rewrite/

For a Hermes ambient agent running on a VPS issuing git log --stat -2 hourly:

  • Raw: ~200K tokens/day from that one command
  • RTK: ~2,592 tokens/day That difference compounds fast at Sonnet 4.6 input pricing.

Analytics

rtk gain          # total savings since install
rtk gain --graph  # visualize savings over time
rtk discover      # scan history for commands RTK could have compressed but didn't
rtk session       # per-session breakdown

rtk discover is the most useful first command — shows filter coverage gaps against your real workflow, not a generic README table.

Limitations

Limitation Detail
Bash-only Claude Code's native Read, Grep, Glob bypass the hook — route via shell or call rtk read/rtk grep explicitly
Windows (native) No hook → falls back to CLAUDE.md instruction injection — strictly weaker. WSL = full parity
Filter coverage 100+ commands supported; anything outside passes raw. Use rtk discover to find gaps
Telemetry Opt-in, disabled by default, anonymised — review docs/TELEMETRY.md before opting in

Decision Matrix

Use RTK when Skip it when
Long Claude Code / Cursor / Hermes sessions with heavy git/test/build activity Agent primarily uses native file-read tools (Read/Grep/Glob)
Cost- or context-window-constrained agentic workflows Native Windows without WSL
You want measurable, persistent savings analytics Commands fall outside the 100+ supported filter list

vs Headroom

RTK and Headroom are not competing — Headroom bundles RTK as a dependency.

Layer RTK Headroom
Shell command output ✅ 98%+ savings ✅ Via bundled RTK
JSON tool outputs / RAG ❌ ✅ SmartCrusher
Source code blobs ❌ ✅ CodeCompressor
Prose / chat history ❌ ✅ Kompress (optional ML)
Overhead <10ms Low–moderate
Reversibility ❌ (tee log only) ✅ CCR + headroom_retrieve

RTK alone → dev-loop sessions, zero config, deterministic. RTK + Headroom → RAG-heavy agents, long sessions, prose context. headroom wrap claude gives you both automatically.

Hermes Wiki