Copilot instructions

1# Copilot Instructions for rtk
2 
3**rtk (Rust Token Killer)** is a CLI proxy that filters and compresses command outputs before they reach an LLM context, cutting 60-90% of bash output. It wraps common tools (`git`, `cargo`, `grep`, `pnpm`, `go`, etc.) and outputs condensed summaries instead of raw output. Percentages measure bash output, not billed tokens; RTK ships no tokenizer (`src/core/tracking.rs` estimates `bytes / 4`).
4 
5## Using rtk in this session
6 
7**Always prefix commands with `rtk` when running shell commands** — this reduces token consumption for every operation you perform.
8 
9```bash
10# Instead of:              Use:
11git status                 rtk git status
12git log -10                rtk git log -10
13cargo test                 rtk cargo test
14cargo clippy --all-targets rtk cargo clippy --all-targets
15grep -r "pattern" src/     rtk grep -r "pattern" src/
16```
17 
18**rtk meta-commands** (always use these directly, no prefix needed):
19```bash
20rtk gain              # Show token savings analytics
21rtk gain --history    # Full command history with per-command savings
22rtk discover          # Scan session history for missed rtk opportunities
23rtk proxy <cmd>       # Run a command raw (no filtering) but still track it
24```
25 
26**Verify rtk is installed before starting:**
27```bash
28rtk --version   # Should print: rtk X.Y.Z
29rtk gain        # Should show a dashboard (not "command not found")
30```
31 
32> Name collision: `rtk gain` failing means you have `reachingforthejack/rtk` (Rust Type Kit) installed instead. Run `which rtk` to check.
33 
34## Build, Test & Lint
35 
36```bash
37cargo build                    # Development build
38cargo test                     # All tests
39cargo test test_name           # Single test
40cargo test module::tests::     # Module tests
41cargo test -- --nocapture      # With stdout
42 
43# Pre-commit gate (must all pass before any PR)
44cargo fmt --all --check && cargo clippy --all-targets && cargo test
45
46bash scripts/test-all.sh       # Smoke tests (requires installed binary)
47```
48 
49PRs target the **`develop`** branch, not `main`. All commits require a DCO sign-off (`git commit -s`).
50 
51## Architecture
52 
53rtk routes CLI commands via a Clap `Commands` enum in `main.rs` to specialized filter modules in `src/cmds/*/`, each executing the underlying command and compressing output. Token savings are tracked in SQLite via `src/core/tracking.rs`.
54 
55For full details see [ARCHITECTURE.md](../docs/contributing/ARCHITECTURE.md) and [docs/contributing/TECHNICAL.md](../docs/contributing/TECHNICAL.md). Module responsibilities are documented in each folder's `README.md` and each file's `//!` doc header.
56 
57## Key Conventions
58 
59- **Error handling**: `anyhow::Result` with `.context("description")?` — no bare `?`, no `unwrap()` in production. Filters must fall back to raw command on error.
60- **Regex**: Use `LazyLock<Regex>` for fixed patterns reused across calls; keep runtime-dependent patterns local.
61- **Testing**: Unit tests inside modules (`#[cfg(test)] mod tests`). Fixtures in `tests/fixtures/`. Token savings assertions with `count_tokens()`.
62- **Exit codes**: Preserve the underlying command's exit code via `std::process::exit(code)`.
63- **Performance**: Startup <10ms (no async runtime), binary <5MB stripped.
64- **Branch naming**: `fix(scope):`, `feat(scope):`, `chore(scope):` where scope is the affected component.
65 
66For the full contribution workflow, design philosophy, and new-filter checklist, see [CONTRIBUTING.md](../CONTRIBUTING.md).
67