rtk-run

name	rtk-run
description	Use BEFORE running any shell command to decide rtk_run vs native shell. Default to rtk_run for all commands EXCEPT interactive (dev servers, watch mode, REPLs), file mutations (rm/mv/cp/mkdir/chmod/touch), raw JSON/parser output, or commands the user explicitly wants unfiltered.

RTK Run

Overview

RTK compacts verbose command output into concise summaries, saving tokens and context window. Desktop MCP clients do not auto-rewrite commands — you must choose RTK explicitly.

Core principle: When a command may produce long output and is non-interactive, route it through RTK for compact results.

When to Use

digraph rtk_decision {
    "Non-interactive command?" [shape=diamond];
    "Output may be long?" [shape=diamond];
    "RTK support certain?" [shape=diamond];
    "Call rtk_should_use" [shape=box];
    "useRtk true?" [shape=diamond];
    "Call rtk_run" [shape=doublecircle];
    "Use native shell" [shape=doublecircle];

    "Non-interactive command?" -> "Output may be long?" [label="yes"];
    "Non-interactive command?" -> "Use native shell" [label="no"];
    "Output may be long?" -> "RTK support certain?" [label="yes"];
    "Output may be long?" -> "Use native shell" [label="no"];
    "RTK support certain?" -> "Call rtk_run" [label="yes"];
    "RTK support certain?" -> "Call rtk_should_use" [label="unsure"];
    "Call rtk_should_use" -> "useRtk true?" ;
    "useRtk true?" -> "Call rtk_run" [label="yes"];
    "useRtk true?" -> "Use native shell" [label="no"];
}

Use RTK for (100+ commands):

• Files: ls, cat/head/tail → rtk read, find, grep/rg, diff, wc
• Git: git status, git log, git diff, git add, git commit, git push, git pull, git show, git branch, git fetch, git stash
• GitHub CLI: gh pr list, gh pr view, gh issue list, gh run list
• Tests: cargo test, jest, vitest, pytest, go test, playwright test, rake test, rspec
• Build/Lint: cargo build/check/clippy, tsc, eslint/biome, next build, prettier, ruff, mypy, golangci-lint, rubocop, dotnet build
• Package managers: pnpm list, pip list/outdated, bundle install, prisma generate
• Containers: docker ps/images/logs, kubectl pods/logs/services
• Cloud: aws sts/ec2/lambda/s3/logs/cloudformation/dynamodb/iam
• Data: curl, wget, json, env, log, deps

Do NOT use RTK for:

• Interactive commands, dev servers, watch mode, REPLs
• Raw JSON or parser output intended for another program
• File mutation commands: rm, mv, cp, chmod, touch, mkdir
• Commands the user explicitly wants raw/unmodified

Flag-Aware Behavior

RTK respects user intent. When users add verbose flags, RTK compresses less:

Scenario	RTK Behavior
cargo test (default)	Failures only (~90% savings)
cargo test -- --nocapture	Preserves all output (user asked for it)
git log (default)	Compact one-line commits (~80%)
git log --oneline	Already compact, minimal extra savings

Workflow

1. Obviously supported? → Call rtk_run with the original raw command directly.
2. Unsure? → Call rtk_should_use({command}) first.
3. useRtk is true → Call rtk_run with the original raw command (NOT the rewritten string).
4. useRtk is false → Use the native shell/tool.
5. Command fails? → Check if output includes teePath. If yes, use rtk-recover skill.

Quick Reference

Scenario	Action
npm test	rtk_run directly
git log -n 20	rtk_run directly
eslint .	rtk_run directly
cargo build	rtk_run directly
docker ps	rtk_run directly
aws ec2 describe-instances	rtk_run directly
cat large-file.ts	rtk_run (uses rtk read)
npm run dev	Native shell (interactive)
rm -rf dist	Native shell (file mutation)
Unknown command	rtk_should_use first

Ultra-Compact Mode

For extra savings, pass -u flag: rtk -u git log (ASCII icons, inline format).

Custom Filters

If RTK doesn't optimize a specific command well enough, users can create TOML filters:

• Global: ~/.config/rtk/filters/
• Project: <project>/.rtk/filters/

Common Mistakes

Mistake	Fix
Passing rewritten command to rtk_run	Always pass the original raw command
Using RTK for dev servers	Dev servers are interactive — use native shell
Using RTK for rm, mv, cp	File mutations are blocked by security guard
Skipping rtk_should_use for unknown commands	When unsure, always check first
Rerunning raw immediately after RTK failure	Read tee log with rtk_read_log first
Using raw cat instead of rtk read	rtk read smart-filters code files
Not wrapping unknown test commands	rtk test <cmd> wraps any test runner

Red Flags

• About to run an interactive or long-lived command through RTK
• About to pass the rewritten command string instead of the original
• About to use native shell for a command that could benefit from compact output
• Ignoring teePath in failure output
• Running cat on large files instead of rtk read

All of these mean: STOP and reconsider your approach.