diff --git a/.agents/configs/upstream-watch.json b/.agents/configs/upstream-watch.json index 6796d6fde1..710859761e 100644 --- a/.agents/configs/upstream-watch.json +++ b/.agents/configs/upstream-watch.json @@ -1,4 +1,12 @@ { "$comment": "Upstream repos to watch for releases and significant changes. Managed by upstream-watch-helper.sh (t1426). Entry schema: {slug, description, relevance, default_branch, added_at}. State (last_release_seen, last_commit_seen, last_checked, updates_pending) stored in ~/.aidevops/cache/upstream-watch-state.json.", - "repos": [] + "repos": [ + { + "slug": "rtk-ai/rtk", + "description": "CLI proxy that reduces LLM token consumption by 60-90% via smart output filtering", + "relevance": "Token cost optimization for agent bash operations (git, gh, test runners). Evaluated in t1430.", + "default_branch": "master", + "added_at": "2026-03-10" + } + ] } diff --git a/.agents/prompts/build.txt b/.agents/prompts/build.txt index 5e26ca0873..fa5b153ada 100644 --- a/.agents/prompts/build.txt +++ b/.agents/prompts/build.txt @@ -79,6 +79,30 @@ Use TodoWrite frequently to track tasks and show progress. Break complex tasks i - Use `rg --files -g ''` for content + file list - Only use mcp_glob as last resort when Bash is unavailable +# Token-Optimized CLI Output (t1430) +# rtk (https://github.com/rtk-ai/rtk) is an optional CLI proxy that compresses +# command outputs before they reach the LLM context. Single Rust binary, <10ms +# overhead, 60-90% token reduction on git/gh/test commands. +# rtk only affects Bash tool calls — MCP tools (Read, Grep, Glob) are unaffected. +# Helper scripts call git directly in subshells, so rtk does NOT interfere. +- When `rtk` is installed (`command -v rtk`), prefer `rtk` prefix for token-heavy bash commands: + - `rtk git status` instead of `git status` (76-80% reduction) + - `rtk git log -n N` instead of `git log -n N` (86% reduction) + - `rtk git diff` instead of `git diff` (75% reduction) + - `rtk gh pr list` instead of `gh pr list` (29-80% reduction) + - `rtk gh pr view N` instead of `gh pr view N` (87% reduction) +- Do NOT use rtk for file reading (use MCP Read tool) or content search (use MCP Grep tool) +- Do NOT use rtk when exact, structured, or machine-readable output is required: + - API/JSON: `gh api`, `gh ... --json`, `gh ... --jq`, `jq` pipelines + - Porcelain/parseable: `git status --porcelain`, `git diff --stat`, `git log --format='...'` + - Test assertions: test runners where pass/fail counts or assertion messages must be exact + - Pipelines: any command whose output is piped to `grep`, `awk`, `sed`, `cut`, `jq`, or similar parsers + - Verbatim diffs: any diff/log output needed character-for-character (e.g., for patch application) +- If rtk output looks summarized or filtered (missing values, only keys/types), rerun without `rtk` +- Do NOT use rtk in helper scripts — scripts call tools directly, not through the agent +- rtk is optional — if not installed, use commands normally. Never block on rtk absence. +- Telemetry: disable in headless/worker mode (`RTK_TELEMETRY_DISABLED=1`) + # Code Search Priority 1. grep/rg - for exact string matching (fast, zero overhead) 2. Augment Context Engine (semantic search) - for code understanding diff --git a/setup-modules/tool-install.sh b/setup-modules/tool-install.sh index 797436da78..4f04ccb1de 100644 --- a/setup-modules/tool-install.sh +++ b/setup-modules/tool-install.sh @@ -234,6 +234,84 @@ setup_file_discovery_tools() { return 0 } +setup_rtk() { + # rtk — CLI proxy that reduces LLM token consumption by 60-90% (t1430) + # Optional optimization: compresses git/gh/test outputs before they reach LLM context + # Single Rust binary, zero dependencies, <10ms overhead + # https://github.com/rtk-ai/rtk + + # Pin to a tagged release for stability and auditability (Gemini review feedback). + # Update the tag when upstream-watch detects a new release. + local rtk_installer_url="https://raw.githubusercontent.com/rtk-ai/rtk/v0.28.2/install.sh" + + if command -v rtk >/dev/null 2>&1; then + local rtk_version + rtk_version=$(rtk --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1 || echo "unknown") + print_success "rtk found: v$rtk_version (token optimization proxy)" + # Fall through to ensure config is applied (telemetry, tee) + else + print_info "rtk (Rust Token Killer) reduces LLM token usage by 60-90% on CLI commands" + echo " Compresses git, gh, test runner, and linter outputs before they reach the AI context." + echo " Single binary, zero dependencies, <10ms overhead." + echo "" + + local install_rtk="n" + if [[ "$INTERACTIVE_MODE" == "true" ]]; then + read -r -p "Install rtk for token-optimized CLI output? [y/N]: " install_rtk + fi + + if [[ "$install_rtk" =~ ^[Yy]$ ]]; then + VERIFIED_INSTALL_SHELL="sh" + if command -v brew >/dev/null 2>&1; then + if run_with_spinner "Installing rtk via Homebrew" brew install rtk; then + print_success "rtk installed via Homebrew" + else + print_warning "Homebrew install failed, trying curl installer..." + if verified_install "rtk" "$rtk_installer_url"; then + print_success "rtk installed to ~/.local/bin/rtk" + else + print_warning "rtk installation failed (non-critical, optional tool)" + fi + fi + else + # Linux or macOS without brew — use verified_install for secure execution + if verified_install "rtk" "$rtk_installer_url"; then + print_success "rtk installed to ~/.local/bin/rtk" + else + print_warning "rtk installation failed (non-critical, optional tool)" + echo " Manual install: https://github.com/rtk-ai/rtk#installation" + fi + fi + else + print_info "Skipped rtk installation (optional)" + echo " Manual install: brew install rtk OR curl -fsSL $rtk_installer_url | sh" + fi + fi + + # Configure rtk (telemetry off, tee for failure capture) — only if binary is present + if command -v rtk >/dev/null 2>&1; then + local rtk_config_dir="${XDG_CONFIG_HOME:-$HOME/.config}/rtk" + if [[ ! -f "$rtk_config_dir/config.toml" ]]; then + mkdir -p "$rtk_config_dir" + cat >"$rtk_config_dir/config.toml" <<-'RTKEOF' + # rtk configuration (created by aidevops setup.sh) + # https://github.com/rtk-ai/rtk + + [telemetry] + enabled = false + + [tee] + enabled = true + mode = "failures" + max_files = 20 + RTKEOF + print_success "rtk config created (telemetry disabled)" + fi + fi + + return 0 +} + setup_shell_linting_tools() { print_info "Setting up shell linting tools..." diff --git a/setup.sh b/setup.sh index 4fda968381..1e3ab2c3ce 100755 --- a/setup.sh +++ b/setup.sh @@ -664,6 +664,7 @@ main() { confirm_step "Setup MiniSim (iOS/Android emulator launcher)" && setup_minisim confirm_step "Setup Git CLIs (gh, glab, tea)" && setup_git_clis confirm_step "Setup file discovery tools (fd, ripgrep, ripgrep-all)" && setup_file_discovery_tools + confirm_step "Setup rtk (token-optimized CLI output, 60-90% savings)" && setup_rtk confirm_step "Setup shell linting tools (shellcheck, shfmt)" && setup_shell_linting_tools setup_shellcheck_wrapper confirm_step "Setup Qlty CLI (multi-linter code quality)" && setup_qlty_cli diff --git a/todo/tasks/t1430-brief.md b/todo/tasks/t1430-brief.md new file mode 100644 index 0000000000..02f8e377eb --- /dev/null +++ b/todo/tasks/t1430-brief.md @@ -0,0 +1,167 @@ +# t1430: Research rtk-ai/rtk CLI Proxy for Token Reduction Integration + +## Origin + +- **Created:** 2026-03-10 +- **Session:** opencode:rtk-research +- **Created by:** human (user requested research) +- **Conversation context:** User shared and asked to create a research task for integration assessment. + +## What + +Evaluate rtk (Rust Token Killer) — a CLI proxy that intercepts shell command outputs and compresses them before they reach the LLM context — for integration into aidevops framework. + +## Why + +Token consumption is a direct cost driver for AI-assisted development. rtk claims 60-90% reduction on common CLI operations (git, ls, grep, test runners) with <10ms overhead. If validated, this could significantly reduce per-session costs across all aidevops-managed projects. + +## Research Findings + +### rtk Overview + +| Attribute | Value | +|-----------|-------| +| **Repo** | [rtk-ai/rtk](https://github.com/rtk-ai/rtk) | +| **Stars** | 5,842 | +| **License** | MIT | +| **Language** | Rust (single binary, zero deps) | +| **Version** | v0.28.2 (2026-03-10, actively maintained) | +| **Binary size** | ~4.1 MB | +| **Startup overhead** | <10ms | +| **Platforms** | macOS (x86/ARM), Linux (x86/ARM), Windows | + +### How rtk Works + +rtk sits between the LLM agent and shell commands. When an agent runs `git status`, rtk intercepts and compresses the output using command-specific filtering strategies: + +1. **Stats extraction** — `git log` (500 chars) -> `"5 commits, +142/-89"` (20 chars, 96% reduction) +2. **Error-only** — test output (200 lines) -> failures only (20 lines, 90% reduction) +3. **Grouping** — 100 lint errors -> grouped by rule (`no-unused-vars: 23`, 80% reduction) +4. **Deduplication** — repeated log lines -> `[ERROR] ... (x42)` (70% reduction) +5. **Structure-only** — large JSON -> keys + types without values (80% reduction) +6. **Code filtering** — source files -> signatures only, strip bodies (60-90% reduction) + +### Measured Output Compression (on aidevops repo) + +| Command | Raw (bytes) | rtk (bytes) | Reduction | +|---------|-------------|-------------|-----------| +| `git status` (clean) | 100 | 24 | **76%** | +| `git log -5` | 2,556 | 352 | **86%** | +| `gh pr list` | 387 | 274 | **29%** | +| `ls .agents/scripts/` | ~3,000 | ~800 | **~73%** | + +### Integration Mechanism + +rtk offers two modes: + +1. **Prefix mode** — manually prefix commands: `rtk git status` instead of `git status` +2. **Hook mode** — Claude Code `PreToolUse` hook transparently rewrites commands before execution (100% adoption, zero context overhead) + +### Compatibility Assessment + +#### What rtk WOULD compress (Bash tool calls from agents) + +| Operation | Frequency in sessions | rtk savings | Impact | +|-----------|----------------------|-------------|--------| +| `git status/diff/log` | Very high | 75-92% | **High** | +| `git add/commit/push` | High | 92% | **Medium** (already small) | +| `gh pr list/view/create` | Medium | 29-87% | **Medium** | +| `shellcheck`, linters | Medium | 80-85% | **Medium** | +| Test runners | Low-Medium | 90%+ | **Medium** | + +#### What rtk would NOT affect (already optimized) + +| Operation | Why unaffected | +|-----------|---------------| +| MCP Read/Edit/Write/Grep/Glob tools | Bypass shell entirely | +| `git ls-files`, `fd`, `rg` file discovery | build.txt already mandates these over `ls`/`find` — rtk adds marginal value | +| Helper scripts (`*.sh`) | Run in subshell, not intercepted by hook | +| Task/subagent tool calls | MCP protocol, not bash | + +#### Conflict Risk Assessment + +| Concern | Risk | Reason | +|---------|------|--------| +| Helper scripts parsing git output | **None** | Scripts call `git` directly in subshells, rtk hook only intercepts LLM Bash tool calls | +| Exit code preservation | **None** | rtk preserves exit codes by design (critical for CI/CD) | +| `rtk read` replacing `cat` | **Low** | build.txt already forbids `cat` — agents use MCP Read tool | +| `rtk grep` replacing `rg` | **Low** | build.txt mandates MCP Grep tool for content search | +| Compressed git output breaking agent decisions | **Low** | Agents use MCP tools for file ops; git commands are informational | +| Telemetry (daily ping) | **Low** | Opt-out via `RTK_TELEMETRY_DISABLED=1` or config | + +### Platform Compatibility + +| Platform | Status | +|----------|--------| +| Linux x86_64 (our primary) | **Verified** — installed and tested | +| macOS ARM64 | **Supported** — pre-built binary available | +| macOS x86_64 | **Supported** — pre-built binary available | +| Homebrew | **Available** — `brew install rtk` | + +### Cost Savings Projection + +Observability metrics are empty (fresh install), so projecting from rtk's benchmarks: + +**Typical 30-min aidevops session (estimated):** + +| Operation | Frequency | Standard tokens | rtk tokens | Saved | +|-----------|-----------|----------------|------------|-------| +| git status/diff/log | 15x | 5,000 | 1,000 | 4,000 | +| gh pr/issue ops | 5x | 2,000 | 600 | 1,400 | +| Linter/test output | 5x | 10,000 | 1,500 | 8,500 | +| ls/find (residual bash) | 3x | 600 | 150 | 450 | +| **Subtotal bash** | | **17,600** | **3,250** | **14,350 (81%)** | + +**Important context:** Most file operations in aidevops use MCP tools (Read, Grep, Glob), not bash. The 81% reduction applies only to the bash-command subset of token usage. Overall session token reduction would be lower — estimated **15-25%** of total tokens, depending on the ratio of bash vs MCP tool usage. + +At scale (100+ worker sessions/week), even 15-25% reduction is material. + +## Recommendation: ADAPT + +**Adopt rtk as an optional optimization layer, not a mandatory dependency.** + +### Rationale + +1. **Genuine value for bash-heavy operations** — git, gh, test runners see 75-92% reduction. These are real costs. +2. **Zero risk to existing workflows** — rtk only affects Bash tool calls, not MCP tools or helper scripts. Fail-safe: unrecognized commands pass through unchanged. +3. **Low integration cost** — single binary install, no config required for prefix mode. +4. **Partial overlap with existing discipline** — build.txt already mandates `git ls-files`/`fd`/`rg` over `ls`/`find`/`grep`, and MCP Read over `cat`. rtk's biggest wins are in areas we already avoid via bash. +5. **Hook mechanism is platform-specific** — PreToolUse hooks are Claude Code-only. OpenCode (our primary runtime) doesn't have equivalent hooks yet. This limits adoption to manual prefix mode or prompt discipline. + +### Integration Plan + +**Phase 1: Install + prompt guidance (low effort, immediate)** +- Add rtk to `setup.sh` optional tooling (install via curl or brew) +- Add guidance to `build.txt`: "When using Bash for git/gh/test commands, prefer `rtk` prefix for token savings" +- Disable telemetry by default (`RTK_TELEMETRY_DISABLED=1` in dispatch env) +- Add to `upstream-watch.json` for release monitoring + +**Phase 2: Measure actual savings (after Phase 1 deployed)** +- Correlate `rtk gain --format json` data with observability metrics +- Determine actual ROI from real sessions before deeper integration + +**Phase 3: Hook integration (when platform supports it)** +- When OpenCode adds PreToolUse hooks (or equivalent), wire rtk-rewrite.sh for transparent adoption +- This would increase adoption from "when agents remember to prefix" to "100% automatic" + +### What NOT to do + +- Don't make rtk a hard dependency — it's an optimization, not a requirement +- Don't rewrite helper scripts to use rtk — they run in subshells, unaffected +- Don't replace MCP tool guidance with rtk — MCP tools are more reliable for file ops +- Don't enable telemetry in headless/worker mode + +## Acceptance Criteria + +- [x] rtk repo analyzed (architecture, filters, config, hook mechanism) +- [x] Compatibility with aidevops workflows assessed +- [x] Cost savings projected +- [x] rtk installed and tested on target platform +- [x] Recommendation documented with evidence +- [ ] PR with integration plan (Phase 1 scope) + +## References + +- [rtk-ai/rtk](https://github.com/rtk-ai/rtk) — source repo +- [ARCHITECTURE.md](https://github.com/rtk-ai/rtk/blob/master/ARCHITECTURE.md) — technical architecture +- [FEATURES.md](https://github.com/rtk-ai/rtk/blob/master/docs/FEATURES.md) — complete command reference