CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Project Overview
6 
7**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 by 60-90% on common development operations 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.
8 
9This is a fork with critical fixes for git argument parsing and modern JavaScript stack support (pnpm, vitest, Next.js, TypeScript, Playwright, Prisma).
10 
11### Name Collision Warning
12 
13**Two different "rtk" projects exist:**
14- This project: Rust Token Killer (rtk-ai/rtk)
15- reachingforthejack/rtk: Rust Type Kit (DIFFERENT - generates Rust types)
16 
17**Verify correct installation:**
18```bash
19rtk --version  # Should show "rtk 0.28.2" (or newer)
20rtk gain       # Should show token savings stats (NOT "command not found")
21```
22 
23If `rtk gain` fails, you have the wrong package installed.
24 
25## Development Commands
26 
27> **Note**: If rtk is installed, prefer `rtk <cmd>` over raw commands for token-optimized output.
28> All commands work with passthrough support even for subcommands rtk doesn't specifically handle.
29 
30### Build & Run
31```bash
32cargo build                   # raw
33rtk cargo build               # preferred (token-optimized)
34cargo build --release         # release build (optimized)
35cargo run -- &lt;command&gt;        # run directly
36cargo install --path .        # install locally
37```
38 
39### Testing
40```bash
41cargo test                    # all tests
42rtk cargo test                # preferred (token-optimized)
43cargo test &lt;test_name&gt;        # specific test
44cargo test &lt;module_name&gt;::    # module tests
45cargo test -- --nocapture     # with stdout
46bash scripts/test-all.sh      # smoke tests (installed binary required)
47```
48 
49### Linting & Quality
50```bash
51cargo check                   # check without building
52cargo fmt                     # format code
53cargo clippy --all-targets    # all clippy lints
54rtk cargo clippy --all-targets # preferred
55```
56 
57### Pre-commit Gate
58```bash
59cargo fmt --all && cargo clippy --all-targets && cargo test --all
60```
61 
62### Package Building
63```bash
64cargo deb                     # DEB package (needs cargo-deb)
65cargo generate-rpm            # RPM package (needs cargo-generate-rpm, after release build)
66```
67 
68## Architecture
69 
70rtk uses a **command proxy architecture**: `main.rs` routes CLI commands via a Clap `Commands` enum to specialized filter modules in `src/cmds/*/`, each of which executes the underlying command and compresses its output. Token savings are tracked in SQLite via `src/core/tracking.rs`.
71 
72For the full architecture, component details, and module development patterns, see:
73- [ARCHITECTURE.md](docs/contributing/ARCHITECTURE.md) — System design, module organization, filtering strategies, error handling
74- [docs/contributing/TECHNICAL.md](docs/contributing/TECHNICAL.md) — End-to-end flow, folder map, hook system, filter pipeline
75 
76Module responsibilities are documented in each folder's `README.md` and each file's `//!` doc header. Browse `src/cmds/*/` to discover available filters.
77 
78Supported ecosystems: git/gh/gt, cargo, go/golangci-lint, npm/pnpm/npx, ruff/pytest/pip/mypy, rspec/rubocop/rake, dotnet, playwright/vitest/jest, docker/kubectl/aws, gradlew/mvn, php/artisan/phpunit/phpstan/pest.
79 
80### Proxy Mode
81 
82**Purpose**: Execute commands without filtering but track usage for metrics.
83 
84**Usage**: `rtk proxy <command> [args...]`
85 
86**Benefits**:
87- **Bypass RTK filtering**: Workaround bugs or get full unfiltered output
88- **Track usage metrics**: Measure which commands Claude uses most (visible in `rtk gain --history`)
89- **Guaranteed compatibility**: Always works even if RTK doesn't implement the command
90 
91**Examples**:
92```bash
93rtk proxy git log --oneline -20    # Full git log output (no truncation)
94rtk proxy npm install express      # Raw npm output (no filtering)
95rtk proxy curl https://api.example.com/data  # Any command works
96```
97 
98All proxy commands appear in `rtk gain --history` with 0% bash output reduction (input = output).
99 
100## Coding Rules
101 
102Rust patterns, error handling, and anti-patterns are defined in `.claude/rules/rust-patterns.md` (auto-loaded into context). Key points:
103 
104- **anyhow::Result** everywhere, always `.context("description")?`
105- **No unwrap()** in production code
106- **`LazyLock` statics** for all regex (never compile on every function call)
107- **Fallback pattern**: if filter fails, execute raw command unchanged
108- **No async**: single-threaded by design (startup <10ms)
109- **Exit code propagation**: `std::process::exit(code)` on child failure
110 
111Testing strategy and performance targets are defined in `.claude/rules/cli-testing.md` (auto-loaded). Key targets: <10ms startup, <5MB memory, 60-90% reduction in bash output bytes.
112 
113For contribution workflow and design philosophy, see [CONTRIBUTING.md](CONTRIBUTING.md). For the step-by-step filter implementation checklist, see [src/cmds/README.md](src/cmds/README.md#adding-a-new-command-filter).
114 
115## Build Verification (Mandatory)
116 
117**CRITICAL**: After ANY Rust file edits, ALWAYS run the full quality check pipeline before committing:
118 
119```bash
120cargo fmt --all && cargo clippy --all-targets && cargo test --all
121```
122 
123**Rules**:
124- Never commit code that hasn't passed all 3 checks
125- Fix ALL clippy warnings before moving on (zero tolerance)
126- If build fails, fix it immediately before continuing to next task
127 
128**Performance verification** (for filter changes):
129```bash
130hyperfine 'rtk git log -10' --warmup 3          # before
131cargo build --release
132hyperfine 'target/release/rtk git log -10' --warmup 3  # after (should be <10ms)
133```
134 
135## Working Directory Confirmation
136 
137**ALWAYS confirm working directory before starting any work**:
138 
139```bash
140pwd  # Verify you're in the rtk project root
141git branch  # Verify correct branch (main, feature/*, etc.)
142```
143 
144**Never assume** which project to work in. Always verify before file operations.
145 
146## Avoiding Rabbit Holes
147 
148**Stay focused on the task**. Do not make excessive operations to verify external APIs, documentation, or edge cases unless explicitly asked.
149 
150**Rule**: If verification requires more than 3-4 exploratory commands, STOP and ask the user whether to continue or trust available info.
151 
152**Examples of rabbit holes to avoid**:
153- Excessive regex pattern testing (trust snapshot tests, don't manually verify 20 edge cases)
154- Deep diving into external command documentation (use fixtures, don't research git/cargo internals)
155- Over-testing cross-platform behavior (test macOS + Linux, trust CI for Windows)
156- Verifying API signatures across multiple crate versions (use docs.rs if needed, don't clone repos)
157 
158**When to stop and ask**:
159- "Should I research X external API behavior?" → ASK if it requires >3 commands
160- "Should I test Y edge case?" → ASK if not mentioned in requirements
161- "Should I verify Z across N platforms?" → ASK if N > 2
162 
163## Plan Execution Protocol
164 
165When user provides a numbered plan (QW1-QW4, Phase 1-5, sprint tasks, etc.):
166 
1671. **Execute sequentially**: Follow plan order unless explicitly told otherwise
1682. **Commit after each logical step**: One commit per completed phase/task
1693. **Never skip or reorder**: If a step is blocked, report it and ask before proceeding
1704. **Track progress**: Use task list (TaskCreate/TaskUpdate) for plans with 3+ steps
1715. **Validate assumptions**: Before starting, verify all referenced file paths exist and working directory is correct
172