{"owner":"rtk-ai","repo":"rtk","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md",".github/copilot-instructions.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\n**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.\n\nThis is a fork with critical fixes for git argument parsing and modern JavaScript stack support (pnpm, vitest, Next.js, TypeScript, Playwright, Prisma).\n\n### Name Collision Warning\n\n**Two different \"rtk\" projects exist:**\n- This project: Rust Token Killer (rtk-ai/rtk)\n- reachingforthejack/rtk: Rust Type Kit (DIFFERENT - generates Rust types)\n\n**Verify correct installation:**\n```bash\nrtk --version  # Should show \"rtk 0.28.2\" (or newer)\nrtk gain       # Should show token savings stats (NOT \"command not found\")\n```\n\nIf `rtk gain` fails, you have the wrong package installed.\n\n## Development Commands\n\n> **Note**: If rtk is installed, prefer `rtk <cmd>` over raw commands for token-optimized output.\n> All commands work with passthrough support even for subcommands rtk doesn't specifically handle.\n\n### Build & Run\n```bash\ncargo build                   # raw\nrtk cargo build               # preferred (token-optimized)\ncargo build --release         # release build (optimized)\ncargo run -- <command>        # run directly\ncargo install --path .        # install locally\n```\n\n### Testing\n```bash\ncargo test                    # all tests\nrtk cargo test                # preferred (token-optimized)\ncargo test <test_name>        # specific test\ncargo test <module_name>::    # module tests\ncargo test -- --nocapture     # with stdout\nbash scripts/test-all.sh      # smoke tests (installed binary required)\n```\n\n### Linting & Quality\n```bash\ncargo check                   # check without building\ncargo fmt                     # format code\ncargo clippy --all-targets    # all clippy lints\nrtk cargo clippy --all-targets # preferred\n```\n\n### Pre-commit Gate\n```bash\ncargo fmt --all && cargo clippy --all-targets && cargo test --all\n```\n\n### Package Building\n```bash\ncargo deb                     # DEB package (needs cargo-deb)\ncargo generate-rpm            # RPM package (needs cargo-generate-rpm, after release build)\n```\n\n## Architecture\n\nrtk 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`.\n\nFor the full architecture, component details, and module development patterns, see:\n- [ARCHITECTURE.md](docs/contributing/ARCHITECTURE.md) — System design, module organization, filtering strategies, error handling\n- [docs/contributing/TECHNICAL.md](docs/contributing/TECHNICAL.md) — End-to-end flow, folder map, hook system, filter pipeline\n\nModule responsibilities are documented in each folder's `README.md` and each file's `//!` doc header. Browse `src/cmds/*/` to discover available filters.\n\nSupported 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.\n\n### Proxy Mode\n\n**Purpose**: Execute commands without filtering but track usage for metrics.\n\n**Usage**: `rtk proxy <command> [args...]`\n\n**Benefits**:\n- **Bypass RTK filtering**: Workaround bugs or get full unfiltered output\n- **Track usage metrics**: Measure which commands Claude uses most (visible in `rtk gain --history`)\n- **Guaranteed compatibility**: Always works even if RTK doesn't implement the command\n\n**Examples**:\n```bash\nrtk proxy git log --oneline -20    # Full git log output (no truncation)\nrtk proxy npm install express      # Raw npm output (no filtering)\nrtk proxy curl https://api.example.com/data  # Any command works\n```\n\nAll proxy commands appear in `rtk gain --history` with 0% bash output reduction (input = output).\n\n## Coding Rules\n\nRust patterns, error handling, and anti-patterns are defined in `.claude/rules/rust-patterns.md` (auto-loaded into context). Key points:\n\n- **anyhow::Result** everywhere, always `.context(\"description\")?`\n- **No unwrap()** in production code\n- **`LazyLock` statics** for all regex (never compile on every function call)\n- **Fallback pattern**: if filter fails, execute raw command unchanged\n- **No async**: single-threaded by design (startup <10ms)\n- **Exit code propagation**: `std::process::exit(code)` on child failure\n\nTesting 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.\n\nFor 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).\n\n## Build Verification (Mandatory)\n\n**CRITICAL**: After ANY Rust file edits, ALWAYS run the full quality check pipeline before committing:\n\n```bash\ncargo fmt --all && cargo clippy --all-targets && cargo test --all\n```\n\n**Rules**:\n- Never commit code that hasn't passed all 3 checks\n- Fix ALL clippy warnings before moving on (zero tolerance)\n- If build fails, fix it immediately before continuing to next task\n\n**Performance verification** (for filter changes):\n```bash\nhyperfine 'rtk git log -10' --warmup 3          # before\ncargo build --release\nhyperfine 'target/release/rtk git log -10' --warmup 3  # after (should be <10ms)\n```\n\n## Working Directory Confirmation\n\n**ALWAYS confirm working directory before starting any work**:\n\n```bash\npwd  # Verify you're in the rtk project root\ngit branch  # Verify correct branch (main, feature/*, etc.)\n```\n\n**Never assume** which project to work in. Always verify before file operations.\n\n## Avoiding Rabbit Holes\n\n**Stay focused on the task**. Do not make excessive operations to verify external APIs, documentation, or edge cases unless explicitly asked.\n\n**Rule**: If verification requires more than 3-4 exploratory commands, STOP and ask the user whether to continue or trust available info.\n\n**Examples of rabbit holes to avoid**:\n- Excessive regex pattern testing (trust snapshot tests, don't manually verify 20 edge cases)\n- Deep diving into external command documentation (use fixtures, don't research git/cargo internals)\n- Over-testing cross-platform behavior (test macOS + Linux, trust CI for Windows)\n- Verifying API signatures across multiple crate versions (use docs.rs if needed, don't clone repos)\n\n**When to stop and ask**:\n- \"Should I research X external API behavior?\" → ASK if it requires >3 commands\n- \"Should I test Y edge case?\" → ASK if not mentioned in requirements\n- \"Should I verify Z across N platforms?\" → ASK if N > 2\n\n## Plan Execution Protocol\n\nWhen user provides a numbered plan (QW1-QW4, Phase 1-5, sprint tasks, etc.):\n\n1. **Execute sequentially**: Follow plan order unless explicitly told otherwise\n2. **Commit after each logical step**: One commit per completed phase/task\n3. **Never skip or reorder**: If a step is blocked, report it and ask before proceeding\n4. **Track progress**: Use task list (TaskCreate/TaskUpdate) for plans with 3+ steps\n5. **Validate assumptions**: Before starting, verify all referenced file paths exist and working directory is correct\n",".github/copilot-instructions.md":"# Copilot Instructions for rtk\n\n**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`).\n\n## Using rtk in this session\n\n**Always prefix commands with `rtk` when running shell commands** — this reduces token consumption for every operation you perform.\n\n```bash\n# Instead of:              Use:\ngit status                 rtk git status\ngit log -10                rtk git log -10\ncargo test                 rtk cargo test\ncargo clippy --all-targets rtk cargo clippy --all-targets\ngrep -r \"pattern\" src/     rtk grep -r \"pattern\" src/\n```\n\n**rtk meta-commands** (always use these directly, no prefix needed):\n```bash\nrtk gain              # Show token savings analytics\nrtk gain --history    # Full command history with per-command savings\nrtk discover          # Scan session history for missed rtk opportunities\nrtk proxy <cmd>       # Run a command raw (no filtering) but still track it\n```\n\n**Verify rtk is installed before starting:**\n```bash\nrtk --version   # Should print: rtk X.Y.Z\nrtk gain        # Should show a dashboard (not \"command not found\")\n```\n\n> Name collision: `rtk gain` failing means you have `reachingforthejack/rtk` (Rust Type Kit) installed instead. Run `which rtk` to check.\n\n## Build, Test & Lint\n\n```bash\ncargo build                    # Development build\ncargo test                     # All tests\ncargo test test_name           # Single test\ncargo test module::tests::     # Module tests\ncargo test -- --nocapture      # With stdout\n\n# Pre-commit gate (must all pass before any PR)\ncargo fmt --all --check && cargo clippy --all-targets && cargo test\n\nbash scripts/test-all.sh       # Smoke tests (requires installed binary)\n```\n\nPRs target the **`develop`** branch, not `main`. All commits require a DCO sign-off (`git commit -s`).\n\n## Architecture\n\nrtk 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`.\n\nFor 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.\n\n## Key Conventions\n\n- **Error handling**: `anyhow::Result` with `.context(\"description\")?` — no bare `?`, no `unwrap()` in production. Filters must fall back to raw command on error.\n- **Regex**: Use `LazyLock<Regex>` for fixed patterns reused across calls; keep runtime-dependent patterns local.\n- **Testing**: Unit tests inside modules (`#[cfg(test)] mod tests`). Fixtures in `tests/fixtures/`. Token savings assertions with `count_tokens()`.\n- **Exit codes**: Preserve the underlying command's exit code via `std::process::exit(code)`.\n- **Performance**: Startup <10ms (no async runtime), binary <5MB stripped.\n- **Branch naming**: `fix(scope):`, `feat(scope):`, `chore(scope):` where scope is the affected component.\n\nFor the full contribution workflow, design philosophy, and new-filter checklist, see [CONTRIBUTING.md](../CONTRIBUTING.md).\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\n**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.\n\nThis is a fork with critical fixes for git argument parsing and modern JavaScript stack support (pnpm, vitest, Next.js, TypeScript, Playwright, Prisma).\n\n### Name Collision Warning\n\n**Two different \"rtk\" projects exist:**\n- This project: Rust Token Killer (rtk-ai/rtk)\n- reachingforthejack/rtk: Rust Type Kit (DIFFERENT - generates Rust types)\n\n**Verify correct installation:**\n```bash\nrtk --version  # Should show \"rtk 0.28.2\" (or newer)\nrtk gain       # Should show token savings stats (NOT \"command not found\")\n```\n\nIf `rtk gain` fails, you have the wrong package installed.\n\n## Development Commands\n\n> **Note**: If rtk is installed, prefer `rtk <cmd>` over raw commands for token-optimized output.\n> All commands work with passthrough support even for subcommands rtk doesn't specifically handle.\n\n### Build & Run\n```bash\ncargo build                   # raw\nrtk cargo build               # preferred (token-optimized)\ncargo build --release         # release build (optimized)\ncargo run -- <command>        # run directly\ncargo install --path .        # install locally\n```\n\n### Testing\n```bash\ncargo test                    # all tests\nrtk cargo test                # preferred (token-optimized)\ncargo test <test_name>        # specific test\ncargo test <module_name>::    # module tests\ncargo test -- --nocapture     # with stdout\nbash scripts/test-all.sh      # smoke tests (installed binary required)\n```\n\n### Linting & Quality\n```bash\ncargo check                   # check without building\ncargo fmt                     # format code\ncargo clippy --all-targets    # all clippy lints\nrtk cargo clippy --all-targets # preferred\n```\n\n### Pre-commit Gate\n```bash\ncargo fmt --all && cargo clippy --all-targets && cargo test --all\n```\n\n### Package Building\n```bash\ncargo deb                     # DEB package (needs cargo-deb)\ncargo generate-rpm            # RPM package (needs cargo-generate-rpm, after release build)\n```\n\n## Architecture\n\nrtk 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`.\n\nFor the full architecture, component details, and module development patterns, see:\n- [ARCHITECTURE.md](docs/contributing/ARCHITECTURE.md) — System design, module organization, filtering strategies, error handling\n- [docs/contributing/TECHNICAL.md](docs/contributing/TECHNICAL.md) — End-to-end flow, folder map, hook system, filter pipeline\n\nModule responsibilities are documented in each folder's `README.md` and each file's `//!` doc header. Browse `src/cmds/*/` to discover available filters.\n\nSupported 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.\n\n### Proxy Mode\n\n**Purpose**: Execute commands without filtering but track usage for metrics.\n\n**Usage**: `rtk proxy <command> [args...]`\n\n**Benefits**:\n- **Bypass RTK filtering**: Workaround bugs or get full unfiltered output\n- **Track usage metrics**: Measure which commands Claude uses most (visible in `rtk gain --history`)\n- **Guaranteed compatibility**: Always works even if RTK doesn't implement the command\n\n**Examples**:\n```bash\nrtk proxy git log --oneline -20    # Full git log output (no truncation)\nrtk proxy npm install express      # Raw npm output (no filtering)\nrtk proxy curl https://api.example.com/data  # Any command works\n```\n\nAll proxy commands appear in `rtk gain --history` with 0% bash output reduction (input = output).\n\n## Coding Rules\n\nRust patterns, error handling, and anti-patterns are defined in `.claude/rules/rust-patterns.md` (auto-loaded into context). Key points:\n\n- **anyhow::Result** everywhere, always `.context(\"description\")?`\n- **No unwrap()** in production code\n- **`LazyLock` statics** for all regex (never compile on every function call)\n- **Fallback pattern**: if filter fails, execute raw command unchanged\n- **No async**: single-threaded by design (startup <10ms)\n- **Exit code propagation**: `std::process::exit(code)` on child failure\n\nTesting 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.\n\nFor 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).\n\n## Build Verification (Mandatory)\n\n**CRITICAL**: After ANY Rust file edits, ALWAYS run the full quality check pipeline before committing:\n\n```bash\ncargo fmt --all && cargo clippy --all-targets && cargo test --all\n```\n\n**Rules**:\n- Never commit code that hasn't passed all 3 checks\n- Fix ALL clippy warnings before moving on (zero tolerance)\n- If build fails, fix it immediately before continuing to next task\n\n**Performance verification** (for filter changes):\n```bash\nhyperfine 'rtk git log -10' --warmup 3          # before\ncargo build --release\nhyperfine 'target/release/rtk git log -10' --warmup 3  # after (should be <10ms)\n```\n\n## Working Directory Confirmation\n\n**ALWAYS confirm working directory before starting any work**:\n\n```bash\npwd  # Verify you're in the rtk project root\ngit branch  # Verify correct branch (main, feature/*, etc.)\n```\n\n**Never assume** which project to work in. Always verify before file operations.\n\n## Avoiding Rabbit Holes\n\n**Stay focused on the task**. Do not make excessive operations to verify external APIs, documentation, or edge cases unless explicitly asked.\n\n**Rule**: If verification requires more than 3-4 exploratory commands, STOP and ask the user whether to continue or trust available info.\n\n**Examples of rabbit holes to avoid**:\n- Excessive regex pattern testing (trust snapshot tests, don't manually verify 20 edge cases)\n- Deep diving into external command documentation (use fixtures, don't research git/cargo internals)\n- Over-testing cross-platform behavior (test macOS + Linux, trust CI for Windows)\n- Verifying API signatures across multiple crate versions (use docs.rs if needed, don't clone repos)\n\n**When to stop and ask**:\n- \"Should I research X external API behavior?\" → ASK if it requires >3 commands\n- \"Should I test Y edge case?\" → ASK if not mentioned in requirements\n- \"Should I verify Z across N platforms?\" → ASK if N > 2\n\n## Plan Execution Protocol\n\nWhen user provides a numbered plan (QW1-QW4, Phase 1-5, sprint tasks, etc.):\n\n1. **Execute sequentially**: Follow plan order unless explicitly told otherwise\n2. **Commit after each logical step**: One commit per completed phase/task\n3. **Never skip or reorder**: If a step is blocked, report it and ask before proceeding\n4. **Track progress**: Use task list (TaskCreate/TaskUpdate) for plans with 3+ steps\n5. **Validate assumptions**: Before starting, verify all referenced file paths exist and working directory is correct\n",".github/copilot-instructions.md":"# Copilot Instructions for rtk\n\n**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`).\n\n## Using rtk in this session\n\n**Always prefix commands with `rtk` when running shell commands** — this reduces token consumption for every operation you perform.\n\n```bash\n# Instead of:              Use:\ngit status                 rtk git status\ngit log -10                rtk git log -10\ncargo test                 rtk cargo test\ncargo clippy --all-targets rtk cargo clippy --all-targets\ngrep -r \"pattern\" src/     rtk grep -r \"pattern\" src/\n```\n\n**rtk meta-commands** (always use these directly, no prefix needed):\n```bash\nrtk gain              # Show token savings analytics\nrtk gain --history    # Full command history with per-command savings\nrtk discover          # Scan session history for missed rtk opportunities\nrtk proxy <cmd>       # Run a command raw (no filtering) but still track it\n```\n\n**Verify rtk is installed before starting:**\n```bash\nrtk --version   # Should print: rtk X.Y.Z\nrtk gain        # Should show a dashboard (not \"command not found\")\n```\n\n> Name collision: `rtk gain` failing means you have `reachingforthejack/rtk` (Rust Type Kit) installed instead. Run `which rtk` to check.\n\n## Build, Test & Lint\n\n```bash\ncargo build                    # Development build\ncargo test                     # All tests\ncargo test test_name           # Single test\ncargo test module::tests::     # Module tests\ncargo test -- --nocapture      # With stdout\n\n# Pre-commit gate (must all pass before any PR)\ncargo fmt --all --check && cargo clippy --all-targets && cargo test\n\nbash scripts/test-all.sh       # Smoke tests (requires installed binary)\n```\n\nPRs target the **`develop`** branch, not `main`. All commits require a DCO sign-off (`git commit -s`).\n\n## Architecture\n\nrtk 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`.\n\nFor 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.\n\n## Key Conventions\n\n- **Error handling**: `anyhow::Result` with `.context(\"description\")?` — no bare `?`, no `unwrap()` in production. Filters must fall back to raw command on error.\n- **Regex**: Use `LazyLock<Regex>` for fixed patterns reused across calls; keep runtime-dependent patterns local.\n- **Testing**: Unit tests inside modules (`#[cfg(test)] mod tests`). Fixtures in `tests/fixtures/`. Token savings assertions with `count_tokens()`.\n- **Exit codes**: Preserve the underlying command's exit code via `std::process::exit(code)`.\n- **Performance**: Startup <10ms (no async runtime), binary <5MB stripped.\n- **Branch naming**: `fix(scope):`, `feat(scope):`, `chore(scope):` where scope is the affected component.\n\nFor the full contribution workflow, design philosophy, and new-filter checklist, see [CONTRIBUTING.md](../CONTRIBUTING.md).\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\n**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.\n\nThis is a fork with critical fixes for git argument parsing and modern JavaScript stack support (pnpm, vitest, Next.js, TypeScript, Playwright, Prisma).\n\n### Name Collision Warning\n\n**Two different \"rtk\" projects exist:**\n- This project: Rust Token Killer (rtk-ai/rtk)\n- reachingforthejack/rtk: Rust Type Kit (DIFFERENT - generates Rust types)\n\n**Verify correct installation:**\n```bash\nrtk --version  # Should show \"rtk 0.28.2\" (or newer)\nrtk gain       # Should show token savings stats (NOT \"command not found\")\n```\n\nIf `rtk gain` fails, you have the wrong package installed.\n\n## Development Commands\n\n> **Note**: If rtk is installed, prefer `rtk <cmd>` over raw commands for token-optimized output.\n> All commands work with passthrough support even for subcommands rtk doesn't specifically handle.\n\n### Build & Run\n```bash\ncargo build                   # raw\nrtk cargo build               # preferred (token-optimized)\ncargo build --release         # release build (optimized)\ncargo run -- <command>        # run directly\ncargo install --path .        # install locally\n```\n\n### Testing\n```bash\ncargo test                    # all tests\nrtk cargo test                # preferred (token-optimized)\ncargo test <test_name>        # specific test\ncargo test <module_name>::    # module tests\ncargo test -- --nocapture     # with stdout\nbash scripts/test-all.sh      # smoke tests (installed binary required)\n```\n\n### Linting & Quality\n```bash\ncargo check                   # check without building\ncargo fmt                     # format code\ncargo clippy --all-targets    # all clippy lints\nrtk cargo clippy --all-targets # preferred\n```\n\n### Pre-commit Gate\n```bash\ncargo fmt --all && cargo clippy --all-targets && cargo test --all\n```\n\n### Package Building\n```bash\ncargo deb                     # DEB package (needs cargo-deb)\ncargo generate-rpm            # RPM package (needs cargo-generate-rpm, after release build)\n```\n\n## Architecture\n\nrtk 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`.\n\nFor the full architecture, component details, and module development patterns, see:\n- [ARCHITECTURE.md](docs/contributing/ARCHITECTURE.md) — System design, module organization, filtering strategies, error handling\n- [docs/contributing/TECHNICAL.md](docs/contributing/TECHNICAL.md) — End-to-end flow, folder map, hook system, filter pipeline\n\nModule responsibilities are documented in each folder's `README.md` and each file's `//!` doc header. Browse `src/cmds/*/` to discover available filters.\n\nSupported 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.\n\n### Proxy Mode\n\n**Purpose**: Execute commands without filtering but track usage for metrics.\n\n**Usage**: `rtk proxy <command> [args...]`\n\n**Benefits**:\n- **Bypass RTK filtering**: Workaround bugs or get full unfiltered output\n- **Track usage metrics**: Measure which commands Claude uses most (visible in `rtk gain --history`)\n- **Guaranteed compatibility**: Always works even if RTK doesn't implement the command\n\n**Examples**:\n```bash\nrtk proxy git log --oneline -20    # Full git log output (no truncation)\nrtk proxy npm install express      # Raw npm output (no filtering)\nrtk proxy curl https://api.example.com/data  # Any command works\n```\n\nAll proxy commands appear in `rtk gain --history` with 0% bash output reduction (input = output).\n\n## Coding Rules\n\nRust patterns, error handling, and anti-patterns are defined in `.claude/rules/rust-patterns.md` (auto-loaded into context). Key points:\n\n- **anyhow::Result** everywhere, always `.context(\"description\")?`\n- **No unwrap()** in production code\n- **`LazyLock` statics** for all regex (never compile on every function call)\n- **Fallback pattern**: if filter fails, execute raw command unchanged\n- **No async**: single-threaded by design (startup <10ms)\n- **Exit code propagation**: `std::process::exit(code)` on child failure\n\nTesting 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.\n\nFor 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).\n\n## Build Verification (Mandatory)\n\n**CRITICAL**: After ANY Rust file edits, ALWAYS run the full quality check pipeline before committing:\n\n```bash\ncargo fmt --all && cargo clippy --all-targets && cargo test --all\n```\n\n**Rules**:\n- Never commit code that hasn't passed all 3 checks\n- Fix ALL clippy warnings before moving on (zero tolerance)\n- If build fails, fix it immediately before continuing to next task\n\n**Performance verification** (for filter changes):\n```bash\nhyperfine 'rtk git log -10' --warmup 3          # before\ncargo build --release\nhyperfine 'target/release/rtk git log -10' --warmup 3  # after (should be <10ms)\n```\n\n## Working Directory Confirmation\n\n**ALWAYS confirm working directory before starting any work**:\n\n```bash\npwd  # Verify you're in the rtk project root\ngit branch  # Verify correct branch (main, feature/*, etc.)\n```\n\n**Never assume** which project to work in. Always verify before file operations.\n\n## Avoiding Rabbit Holes\n\n**Stay focused on the task**. Do not make excessive operations to verify external APIs, documentation, or edge cases unless explicitly asked.\n\n**Rule**: If verification requires more than 3-4 exploratory commands, STOP and ask the user whether to continue or trust available info.\n\n**Examples of rabbit holes to avoid**:\n- Excessive regex pattern testing (trust snapshot tests, don't manually verify 20 edge cases)\n- Deep diving into external command documentation (use fixtures, don't research git/cargo internals)\n- Over-testing cross-platform behavior (test macOS + Linux, trust CI for Windows)\n- Verifying API signatures across multiple crate versions (use docs.rs if needed, don't clone repos)\n\n**When to stop and ask**:\n- \"Should I research X external API behavior?\" → ASK if it requires >3 commands\n- \"Should I test Y edge case?\" → ASK if not mentioned in requirements\n- \"Should I verify Z across N platforms?\" → ASK if N > 2\n\n## Plan Execution Protocol\n\nWhen user provides a numbered plan (QW1-QW4, Phase 1-5, sprint tasks, etc.):\n\n1. **Execute sequentially**: Follow plan order unless explicitly told otherwise\n2. **Commit after each logical step**: One commit per completed phase/task\n3. **Never skip or reorder**: If a step is blocked, report it and ask before proceeding\n4. **Track progress**: Use task list (TaskCreate/TaskUpdate) for plans with 3+ steps\n5. **Validate assumptions**: Before starting, verify all referenced file paths exist and working directory is correct\n","category":"root","tokens":1927},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","title":"copilot-instructions.md","content":"# Copilot Instructions for rtk\n\n**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`).\n\n## Using rtk in this session\n\n**Always prefix commands with `rtk` when running shell commands** — this reduces token consumption for every operation you perform.\n\n```bash\n# Instead of:              Use:\ngit status                 rtk git status\ngit log -10                rtk git log -10\ncargo test                 rtk cargo test\ncargo clippy --all-targets rtk cargo clippy --all-targets\ngrep -r \"pattern\" src/     rtk grep -r \"pattern\" src/\n```\n\n**rtk meta-commands** (always use these directly, no prefix needed):\n```bash\nrtk gain              # Show token savings analytics\nrtk gain --history    # Full command history with per-command savings\nrtk discover          # Scan session history for missed rtk opportunities\nrtk proxy <cmd>       # Run a command raw (no filtering) but still track it\n```\n\n**Verify rtk is installed before starting:**\n```bash\nrtk --version   # Should print: rtk X.Y.Z\nrtk gain        # Should show a dashboard (not \"command not found\")\n```\n\n> Name collision: `rtk gain` failing means you have `reachingforthejack/rtk` (Rust Type Kit) installed instead. Run `which rtk` to check.\n\n## Build, Test & Lint\n\n```bash\ncargo build                    # Development build\ncargo test                     # All tests\ncargo test test_name           # Single test\ncargo test module::tests::     # Module tests\ncargo test -- --nocapture      # With stdout\n\n# Pre-commit gate (must all pass before any PR)\ncargo fmt --all --check && cargo clippy --all-targets && cargo test\n\nbash scripts/test-all.sh       # Smoke tests (requires installed binary)\n```\n\nPRs target the **`develop`** branch, not `main`. All commits require a DCO sign-off (`git commit -s`).\n\n## Architecture\n\nrtk 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`.\n\nFor 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.\n\n## Key Conventions\n\n- **Error handling**: `anyhow::Result` with `.context(\"description\")?` — no bare `?`, no `unwrap()` in production. Filters must fall back to raw command on error.\n- **Regex**: Use `LazyLock<Regex>` for fixed patterns reused across calls; keep runtime-dependent patterns local.\n- **Testing**: Unit tests inside modules (`#[cfg(test)] mod tests`). Fixtures in `tests/fixtures/`. Token savings assertions with `count_tokens()`.\n- **Exit codes**: Preserve the underlying command's exit code via `std::process::exit(code)`.\n- **Performance**: Startup <10ms (no async runtime), binary <5MB stripped.\n- **Branch naming**: `fix(scope):`, `feat(scope):`, `chore(scope):` where scope is the affected component.\n\nFor the full contribution workflow, design philosophy, and new-filter checklist, see [CONTRIBUTING.md](../CONTRIBUTING.md).\n","category":".github","tokens":864}]}