rtk: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

rtk (Rust Token Killer) is a high-performance CLI proxy that minimizes LLM token consumption by filtering and compressing command outputs. It reduces bash output on common development operations (each filter must cut at least 20%; most cut far more) through smart filtering, grouping, truncation, and deduplication. All percentages in this repo measure bash output, not your bill. RTK ships no tokenizer (src/core/tracking.rs estimates tokens as bytes / 4), so the ratios are reliable but the absolute token counts are approximate.

Name Collision Warning

Two different "rtk" projects exist:

• This project: Rust Token Killer (rtk-ai/rtk)
• reachingforthejack/rtk: Rust Type Kit (DIFFERENT - generates Rust types)

Verify correct installation:

rtk --version  # Any current version; the check that matters is the next line
rtk gain       # Should show token savings stats (NOT "command not found")

If rtk gain fails, you have the wrong package installed.

Development Commands

Note: If rtk is installed, prefer rtk <cmd> over raw commands for token-optimized output. All commands work with passthrough support even for subcommands rtk doesn't specifically handle.

Build & Run

cargo build                   # raw
rtk cargo build               # preferred (token-optimized)
cargo build --release         # release build (optimized)
cargo run -- <command>        # run directly
cargo install --path .        # install locally

Testing

cargo test                    # all tests
rtk cargo test                # preferred (token-optimized)
cargo test <test_name>        # specific test
cargo test <module_name>::    # module tests
cargo test -- --nocapture     # with stdout
bash scripts/test-all.sh      # smoke tests (installed binary required)

Linting & Quality

cargo check                   # check without building
cargo fmt                     # format code
cargo clippy --all-targets    # all clippy lints
rtk cargo clippy --all-targets # preferred