GO — Healthy across the board

• Last commit today
• 18 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 63% of recent commits

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

rtk (Rust Token Killer) is a single-binary CLI proxy written in pure Rust that intercepts and compresses command outputs before they reach LLM context windows, reducing token consumption by 60-90% on common dev commands (ls, git, cargo test, grep, etc.). It requires zero external dependencies and adds <10ms overhead while supporting 100+ commands across multiple ecosystems (Node.js, Python, Rust, Go, Docker). Single Rust binary architecture: the root src/ contains the main CLI logic with command routing (inferred from Cargo.toml's automod dependency). The .claude/ directory contains extensive agent prompts and testing rules (rust-rtk.md, rtk-testing-specialist.md), suggesting heavy use of Claude for development decisions. Config uses TOML files (toml = "0.8" dependency) likely stored in dirs::config_dir(). Database storage via rusqlite (SQLite bundled binary).

AI-assisted developers using Claude or other LLMs in their terminal workflow who want to reduce API costs and context window pressure when piping command outputs into LLM prompts. Also useful for DevOps and systems engineers doing frequent git/build command analysis via AI.

Actively maintained and production-ready. The project has reached v0.39.0 with security CI/CD (GitHub Actions), Homebrew distribution, and multi-language README translations (6 languages). However, it's pre-1.0 software with a single primary maintainer (Patrick Szymkowiak), so minor breaking changes may occur in patch releases.

Low structural risk: the Cargo.toml shows only 15 direct dependencies, all well-maintained (clap, serde, regex, rusqlite). Single-maintainer repository is the primary risk; no visible test suite in the file list suggests test coverage may be incomplete. Dependency on zero-copy unsafe code (libc for Unix) requires careful audits on OS-level changes.

Active development on version 0.39.0. The presence of .claude/commands and .claude/agents suggests ongoing AI-assisted feature development and code review. Multiple shell hook scripts (pre-commit-format.sh, rtk-rewrite.sh, rtk-suggest.sh) indicate recent work on integration and suggestion systems. Security CI/CD is in place, suggesting recent hardening efforts.

git clone https://github.com/rtk-ai/rtk.git
cd rtk
rustup update  # ensure Rust 2021 edition support
cargo build --release
./target/release/rtk --version

Or install via Homebrew: brew install rtk

Daily commands: This is a compiled binary tool, not a server. After cargo build --release, invoke directly: rtk <command> [args]. Example: rtk git status or rtk ls -la /large/dir. The binary intercepts and filters the output before returning to stdout.

• src/main.rs — Entry point for the RTK CLI proxy; defines core command routing and initialization logic that all features depend on.
• Cargo.toml — Declares all dependencies and workspace configuration; zero-dependency philosophy is core to RTK's value proposition.
• docs/contributing/ARCHITECTURE.md — Technical blueprint for the codebase structure; required reading for understanding how token filtering and command proxying work together.
• .rtk/filters.toml — Configuration file that defines which command outputs are filtered to reduce token consumption; customization foundation for all users.
• build.rs — Build script that handles compile-time configuration and binary optimization; critical for single-binary distribution strategy.
• README.md — Primary documentation describing the 60-90% token reduction claim, supported agents, and installation; must understand RTK's scope before contributing.

• CLI Router (main.rs) (Clap, std::process) — Accepts user commands, parses arguments via Clap, dispatches to appropriate command handler.
  • Failure mode: Argument parsing error or unknown command → user sees help text; command dispatch failure → falls through to underlying command.
• Filter Engine (Regex, TOML deserialization) — Applies regex-based rules from filters.toml to command output, removing non-essential lines to reduce token count.
  • Failure mode: Invalid filter pattern → filtered output may be incomplete; missing filter config → raw output returned unfiltered.
• Cache Layer (SQLite) (Rusqlite, chrono) — Stores filtered command outputs with configurable TTL to avoid re-filtering repeated commands.
  • Failure mode: Cache corruption → cache bypass and re-filter; disk full → fallback to non-cached mode.
• Command Proxy (std::process::Command, regex) — Intercepts developer commands (git, cargo, etc.), executes them as subprocesses, captures and filters output.
  • Failure mode: Command not found → subprocess error propagates; output encoding issue → malformed filter input.
• Configuration Loader (TOML deserialization, lazy_static) — Reads .rtk/filters.toml and applies user-defined or agent-specific filter rules.
  • Failure mode: TOML syntax error → config load failure; missing filter file → defaults to no filters.
• Telemetry Collector (Rusqlite, chrono) — Tracks token reduction metrics and command usage statistics in SQLite for analytics.
  • Failure mode: Telemetry write error → silent failure (doesn't block command execution); disk quota exceeded → metrics discarded.

• Developer CLI input → CLI Router — User types 'rtk [command] [args]' into terminal
• CLI Router → Command — undefined

Add a New Command Filter

1. Edit .rtk/filters.toml and add a new [[command]] section with patterns for output you want to filter (.rtk/filters.toml)
2. Define regex patterns in the [patterns] section to match lines to remove from command output (.rtk/filters.toml)
3. Test your filter by running rtk with the target command to verify token reduction (docs/contributing/TECHNICAL.md)

Add Support for a New LLM Agent

1. Create a new agent configuration file in .claude/agents/ following the pattern of rust-rtk.md (.claude/agents/rust-rtk.md)
2. Define agent-specific filters and behaviors in the new agent markdown file (.claude/agents/rust-rtk.md)
3. Update docs/guide/getting-started/supported-agents.md to list the new agent (docs/guide/getting-started/supported-agents.md)

Implement a New Development Command Proxy

1. Add command handler code following the pattern established in src/main.rs for routing (src/main.rs)
2. Create filter rules in .rtk/filters.toml for the new command's output (.rtk/filters.toml)
3. Add test cases in docs/contributing/TECHNICAL.md documenting expected behavior (docs/contributing/TECHNICAL.md)

Add a New Telemetry or Analytics Feature

1. Review the telemetry contract and architecture in docs/TELEMETRY.md (docs/TELEMETRY.md)
2. Implement data collection logic in the token filtering engine, using rusqlite for persistence (Cargo.toml)
3. Document new metrics in docs/guide/analytics/ following existing patterns (docs/guide/analytics/discover.md)

• Rust with single binary — Zero dependencies and fast startup/execution minimize overhead when proxying frequent dev commands; compiled binary enables simple distribution via Homebrew.
• Clap for CLI argument parsing — Battle-tested, ergonomic framework for building composable subcommands with minimal code; aligns with RTK's philosophy of thin wrapper layers.
• SQLite (rusqlite) for caching — Lightweight embedded database for persistent filtered output cache and telemetry; no external service dependency required.
• Regex-based filtering with TOML config — Declarative, user-editable configuration language for defining filter rules without code changes; regex handles diverse command output formats.
• Colored for terminal output — Minimal dependency for user-friendly colored diagnostic output and status messages.

• Zero external dependencies philosophy

  • Why: Reduces supply chain risk, attack surface, and binary size; simplifies distribution and eliminates version conflicts.
  • Consequence: Cannot use feature-rich HTTP clients or advanced caching libraries; must implement or use stdlib alternatives.

• Configuration-driven filtering via TOML instead of code-generated rules

  • Why: Allows non-engineers to customize filters without recompilation; supports rapid iteration and agent-specific tuning.
  • Consequence: Filter logic is less flexible than programmatic rules; users must understand regex patterns.

• Local SQLite cache instead of cloud/distributed cache

  • Why: Eliminates external service dependency and latency; privacy-preserving since no data leaves the developer's machine.
  • Consequence: Cannot share cache across team members; scalability limited to single machine storage.

• Simple command wrapping/proxying approach

  • Why: Minimal overhead and compatibility; works with any command already on the developer's PATH.
  • Consequence: Cannot inspect/modify command semantics; relies entirely on output filtering, not semantic analysis.

• Real-time collaborative filtering across multiple developers
• Support for non-POSIX platforms (Windows native support not primary focus)
• Built-in LLM client or authentication management
• Semantic code analysis (regex-based filtering only)
• Multi-language support beyond command output filtering

No .env or secrets file: Configuration likely lives in ~/.config/rtk/ (dirs crate default). SQLite database is bundled: rusqlite's bundled feature means no external SQLite installation required, but this increases binary size (~4-5MB estimated). Regex patterns are compiled at startup: Pattern modifications require recompilation. Unix-specific code path: libc dependency only active on Unix targets (cfg(unix)); Windows support may be limited. No async I/O: All file operations are synchronous (walkdir, ignore crates); very large file lists may pause briefly.

• Output Filtering & Compression Pipeline — rtk's entire value proposition is built on chaining multiple filter stages (strip ANSI codes, truncate long lines, remove boilerplate); understanding the pipeline architecture is essential to add new command support
• Lazy Static Regex Compilation — rtk uses lazy_static to compile regex patterns once at startup; critical for understanding performance characteristics and why modifying patterns requires recompilation
• SQLite Caching Strategy — rusqlite with bundled SQLite allows rtk to cache filtered outputs and avoid re-filtering identical commands; understanding cache TTL and invalidation is key to avoiding stale output bugs
• Token Counting & LLM Context Windows — rtk's entire design assumes familiarity with how LLM tokenizers work (subword tokens, context limits); essential to understand why 60-90% reduction is achievable and realistic
• Binary Path Detection via which Crate — rtk must detect whether git, cargo, npm, etc. exist on the user's PATH before applying command-specific filters; the which crate handles this portably across Unix/Windows
• ANSI Escape Code Stripping — CLI tools emit ANSI color/formatting codes that waste tokens; rtk strips these early in the pipeline; understanding ANSI sequences is essential for debugging filtered output
• Flate2 Compression for Large Outputs — flate2 (zlib) allows rtk to further compress very large command outputs before passing to LLM; understanding when compression is worthwhile vs. overhead tradeoffs is important for optimization

• SimonWaldherr/actionlint — Similar single-binary Rust tool that optimizes CI/CD workflow output; shares minimalist dependency philosophy and release distribution strategy
• BurntSushi/ripgrep — Rust CLI tool for fast text searching used by rtk (grep filtering); shares the pattern of single-binary optimization and zero-dependency design ethos
• OpenAI/gpt-tokenizer — Token counting library; essential companion for understanding the exact token savings rtk claims and for validating compression effectiveness
• aider-ai/aider — AI-assisted coding CLI that consumes command outputs (git, tests, etc.); a primary consumer of rtk in the broader AI-assisted dev ecosystem
• verylongnamethatshouldnotmatch/repo — N/A - no obvious direct predecessor or inspiration repo publicly visible; rtk appears to be an original solution to the token-reduction problem

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for rtk CLI command routing and output filtering

The repo has comprehensive agent definitions (.claude/agents/) and command specs (.claude/commands/) but no visible [dev-dependencies] or test files in src/. Given rtk is a CLI proxy that filters command outputs, integration tests validating that commands are correctly intercepted, filtered, and token counts are reduced would be critical for confidence in the 60-90% token reduction claims. This also validates the command routing logic (.claude/commands/test-routing.md exists, suggesting routing is complex).

• [ ] Create tests/integration_tests.rs with test cases for common commands (e.g., git status, ls, cargo build)
• [ ] Add test fixtures in tests/fixtures/ with sample command outputs and expected filtered results
• [ ] Add insta or similar snapshot testing dependency to Cargo.toml [dev-dependencies] for output validation
• [ ] Test that token count reduction meets the 60-90% claim for at least 3-5 real-world dev commands
• [ ] Reference .claude/commands/test-routing.md to ensure routing test coverage aligns with documented behavior

Add performance benchmarks for token filtering efficiency

Given the core value proposition is 60-90% token reduction, there should be measurable benchmarks. The repo has a performance skill (.claude/skills/performance/SKILL.md) and release optimization settings (opt-level=3, lto=true) but no benches/ directory. Adding Criterion benchmarks would quantify filter performance and catch regressions.

• [ ] Create benches/token_filtering.rs using the Criterion crate
• [ ] Add criterion to [dev-dependencies] in Cargo.toml
• [ ] Benchmark filtering speed and token reduction ratio for representative command outputs (git, cargo, ls, etc.)
• [ ] Document baseline metrics in BENCHMARKS.md with instructions to run cargo bench
• [ ] Integrate benchmark results into the release process (.github/workflows/release.yml) or PR checks

Implement structured logging and diagnostics for the .rtk config and filter application

The repo has a diagnose command (.claude/commands/diagnose.md) and uses rusqlite for persistence, but there's a .rtk file referenced with no documentation. Adding structured debug output would help users and contributors understand how filters are being applied. This fills a gap between the agent definitions and actual runtime behavior.

• [ ] Document the .rtk config file format and location (likely in ~/.rtk or project root) in a new docs/CONFIG.md
• [ ] Add structured logging using a crate like tracing or log to src/main.rs and filter application code
• [ ] Enhance the diagnose command to output: loaded filters, matched patterns, token reduction estimates, and SQLite cache state
• [ ] Add a --debug flag to rtk CLI that enables verbose filter tracing (see .claude/commands/diagnose.md for context)
• [ ] Add 2-3 test cases in tests/ validating diagnose output for various filter scenarios

• Add missing test coverage for the git diff compression logic: the Cargo.toml lacks a [dev-dependencies] section and no test files are listed, suggesting git-related filters lack unit tests. Start with tests/ directory and property-based testing via regex captures.
• Document the SQLite schema and caching strategy: rusqlite is used but no schema.sql file is visible in the file list. Create documentation explaining which command outputs are cached, TTL policies, and how to inspect the cache at ~/.config/rtk/cache.db.
• Implement tree command filtering optimization: the README shows ls/tree at -80% savings, but advanced tree output (--dirsfirst, --charset) may not be handled. Add a new command pattern in the filters module with test cases for nested deep directories.

RTK has a reasonable security foundation as a Rust-based CLI tool with minimal dependencies. Main concerns center on SQLite database security, command execution safety (inherent to the tool's purpose), and supply chain risks from external dependencies. The project demonstrates security awareness (SECURITY.md, responsible disclosure policy) but would benefit from stricter dependency pinning, database encryption, and more comprehensive documentation of input validation patterns. No critical vulnerabilities detected in the provided files, but source code review of actual command execution and data handling is recommended.

• Medium · SQLite Database Exposure Risk — Cargo.toml (rusqlite dependency), potential tracking.db file. The codebase uses rusqlite with bundled SQLite and references 'tracking.db' in SECURITY.md. SQLite databases stored on disk without encryption are vulnerable to unauthorized access if the system is compromised. User data could be extracted directly from the database file. Fix: Implement database encryption at rest using SQLCipher or similar. Restrict file permissions to owner-only (chmod 600). Document data retention policies and implement secure deletion mechanisms for sensitive data.
• Medium · Command Execution with User Input — Core CLI execution logic (not visible in provided files). RTK is a CLI proxy that executes shell commands. While the tool filters outputs, the architecture inherently processes user-supplied commands. Without proper validation and sanitization, there's potential for command injection if user input is not carefully validated before command execution. Fix: Implement strict input validation using allowlists rather than blocklists. Use process spawning APIs that don't invoke shell interpretation (e.g., Command with separate args). Document unsafe patterns and provide examples of safe command construction. Add integration tests for injection vectors.
• Medium · External HTTP Dependency (ureq) — Cargo.toml - ureq = "2". The ureq dependency (version 2) is used without version pinning constraints. This could lead to supply chain attacks if a compromised version is released. Additionally, any network communication should validate certificates and implement timeout protections. Fix: Pin to specific versions (e.g., ureq = "2.9.1") or use conservative ranges with upper bounds. Implement certificate pinning for critical API endpoints. Add timeout configurations and validate all remote content. Regular dependency audits using 'cargo audit' in CI/CD.
• Low · Temporary File Creation Security — Cargo.toml - tempfile = "3". The tempfile dependency is used but without explicit analysis of secure creation patterns. Temporary files could be created in world-readable locations, exposing sensitive intermediate data. Fix: Use tempfile::NamedTempFile or tempfile::TempDir with default secure creation flags. Ensure temporary files are created with restrictive permissions (mode 0600). Verify cleanup on error paths to prevent sensitive data leakage.
• Low · Missing Dependency Hash Verification — Formula/rtk.rb, Release distribution. Cargo.lock exists but the provided structure doesn't show verification mechanisms for binary releases. Users installing via Homebrew should verify binary integrity. Fix: Publish SHA256 checksums for each release. Sign binaries with a GPG key and publish verification instructions. Include checksum verification in installation scripts (brew formula and manual install guides).
• Low · Incomplete Security.md Documentation — SECURITY.md. The SECURITY.md file appears truncated in the provided content ('Security Check' workflow section cut off). The security policy documentation may be incomplete, potentially leaving gaps in vulnerability disclosure processes. Fix: Ensure complete security policy documentation including: vulnerability severity classifications, patch timelines, security contact methods, disclosure timeline expectations, and acknowledgment procedures. Make the document easily discoverable (link from README).
• Low · Debug/Telemetry Data Risk — Core application logic (not provided). SECURITY.md mentions 'telemetry abuse' and 'tracking.db exposure' as concerns. Without source code inspection, unclear if telemetry is properly opt-in only and what data is collected. Fix: Implement opt-in telemetry only (disabled by default). Document all collected data. Implement data retention limits. Provide clear user controls to disable/delete telemetry. Regular privacy audits of data collection practices.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/rtk-ai/rtk shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live rtk-ai/rtk repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/rtk-ai/rtk.

What it runs against: a local clone of rtk-ai/rtk — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in rtk-ai/rtk | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of rtk-ai/rtk. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/rtk-ai/rtk.git
#   cd rtk
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of rtk-ai/rtk and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "rtk-ai/rtk(\\.git)?\\b" \\
  && ok "origin remote is rtk-ai/rtk" \\
  || miss "origin remote is not rtk-ai/rtk (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "docs/contributing/ARCHITECTURE.md" \\
  && ok "docs/contributing/ARCHITECTURE.md" \\
  || miss "missing critical file: docs/contributing/ARCHITECTURE.md"
test -f ".rtk/filters.toml" \\
  && ok ".rtk/filters.toml" \\
  || miss "missing critical file: .rtk/filters.toml"
test -f "build.rs" \\
  && ok "build.rs" \\
  || miss "missing critical file: build.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/rtk-ai/rtk"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.