rtk: Instructions file for GitHub Copilot

Copilot Instructions for rtk

rtk (Rust Token Killer) is a CLI proxy that filters and compresses command outputs before they reach an LLM context. 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).

Using rtk in this session

Always prefix commands with rtk when running shell commands — this reduces token consumption for every operation you perform.

# Instead of:              Use:
git status                 rtk git status
git log -10                rtk git log -10
cargo test                 rtk cargo test
cargo clippy --all-targets rtk cargo clippy --all-targets
grep -r "pattern" src/     rtk grep -r "pattern" src/

rtk meta-commands (always use these directly, no prefix needed):

rtk gain              # Show token savings analytics
rtk gain --history    # Full command history with per-command savings
rtk discover          # Scan session history for missed rtk opportunities
rtk bypass <cmd>       # Run a command raw (no filtering) but still track it

Verify rtk is installed before starting:

rtk --version   # Should print: rtk X.Y.Z
rtk gain        # Should show a dashboard (not "command not found")

Name collision: rtk gain failing means you have reachingforthejack/rtk (Rust Type Kit) installed instead. Run which rtk to check.

Build, Test & Lint

cargo build                    # Development build
cargo test                     # All tests
cargo test test_name           # Single test
cargo test module::tests::     # Module tests
cargo test -- --nocapture      # With stdout

# Pre-commit gate (must all pass before any PR)
cargo fmt --all --check && cargo clippy --all-targets && cargo test

bash scripts/test-all.sh       # Smoke tests (requires installed binary)

PRs target the develop branch, not main. All commits require a DCO sign-off (git commit -s).