Skip to main content

​
What is Proxy Mode?

Proxy mode executes commands without RTK filtering while still recording usage metrics in the tracking database. It provides a safety valve when RTK’s filtering causes issues or you need the full, unfiltered output.
Proxy mode runs the raw command and passes through output unchanged. Token savings are 0%, but execution metrics (command count, timing) are still tracked.

​
Usage

rtk proxy <command> [args...]
Examples: 
# Full git log output (no RTK truncation)
rtk proxy git log --oneline -20

# Raw npm install output (no filtering)
rtk proxy npm install express

# Any command works
rtk proxy curl https://api.example.com/data
rtk proxy docker logs my-container
rtk proxy pytest tests/

​
Benefits

​
1. Bypass RTK Filtering Bugs

If RTK’s filter produces incorrect output: 
# RTK filter may have a bug
rtk git log --graph --all
# Output looks wrong?

# Use proxy mode to get raw git output
rtk proxy git log --graph --all
# Identical to raw `git log --graph --all`

​
2. Track Metrics Without Filtering

Record which commands you use without modifying output: 
# Track usage but preserve full output
rtk proxy cargo build
rtk proxy go test ./...

# Later: see what commands were run
rtk gain --history
# Shows "rtk proxy cargo build" with 0% savings

​
3. Guaranteed Compatibility

Proxy mode works with any command, even if RTK doesn’t implement a filter for it: 
# RTK doesn't have a terraform filter
rtk proxy terraform plan

# RTK doesn't handle kubectl rollout
rtk proxy kubectl rollout status deployment/my-app

​
4. Debugging & Comparison

Compare RTK-filtered vs raw output: 
# RTK filtered
rtk cargo test > filtered.txt

# Raw output
rtk proxy cargo test > raw.txt

# Compare
diff filtered.txt raw.txt

​
Tracking Behavior

Proxy mode tracks commands with 0% savings: 
rtk proxy git status
# Tracked as:
# - original_cmd: "git status"
# - rtk_cmd: "rtk proxy git status"
# - input_tokens: 1000 (raw output)
# - output_tokens: 1000 (same — no filtering)
# - saved_tokens: 0
# - savings_pct: 0.0%
View proxy usage in analytics: 
rtk gain --history
# Output:
# Recent Commands:
# 2026-03-05 10:15 | rtk proxy git log      | 0 saved (0.0%)
# 2026-03-05 10:14 | rtk git status         | 800 saved (80.0%)
Proxy commands appear in rtk gain output with 0% savings, which dilutes overall averages. Use sparingly for production workflows.

​
When to Use Proxy Mode

​
Use Proxy Mode When:

✅ RTK filter produces incorrect output 
rtk git diff  # Shows truncated diff?
rtk proxy git diff  # Get full diff
✅ You need full debugging information 
rtk cargo test  # Shows failures only
rtk proxy cargo test  # Shows all test output (passed + failed)
✅ RTK doesn’t support the command 
rtk proxy terraform apply
rtk proxy ansible-playbook site.yml
✅ You want to track usage without filtering 
# Track which kubectl commands you use most
rtk proxy kubectl get pods
rtk proxy kubectl logs my-pod
rtk gain --history  # See usage patterns

​
Don’t Use Proxy Mode When:

❌ You want token savings — Use regular RTK commands instead 
rtk git status  # ✅ Saves 80% tokens
rtk proxy git status  # ❌ 0% savings
❌ RTK filter works correctly — Proxy wastes LLM context 
rtk cargo test  # ✅ Failures-only output (90% reduction)
rtk proxy cargo test  # ❌ Full verbose output (no benefit)

​
Examples

​
Example 1: Debug RTK Filter

# RTK filter seems broken
rtk git log --graph --all --decorate
# Output looks wrong

# Use proxy to get raw git output
rtk proxy git log --graph --all --decorate
# Identical to raw git — confirms RTK filter has a bug

# Report issue: github.com/rtk-ai/rtk/issues

​
Example 2: Full Test Output for Debugging

# Normal: failures only (90% reduction)
rtk cargo test
# FAILED: 2/15 tests
#   ✗ test_edge_case: assertion failed at src/lib.rs:42

# Proxy: full output including passed tests
rtk proxy cargo test
# running 15 tests
# test utils::test_parse ... ok
# test utils::test_format ... ok
# ...
# test failures::test_edge_case ... FAILED
# ...

​
Example 3: Unsupported Command

# RTK doesn't have a helm filter
rtk helm list
# Error: command not found

# Use proxy mode
rtk proxy helm list
# Works! (passes through to raw helm)

​
Example 4: Track Usage Without Filtering

# Track which commands you use during a session
rtk proxy git checkout main
rtk proxy git pull
rtk proxy npm run dev

# Later: analyze usage patterns
rtk gain --history
# Recent Commands:
# 2026-03-05 14:30 | rtk proxy npm run dev    | 0 saved (0.0%)
# 2026-03-05 14:25 | rtk proxy git pull       | 0 saved (0.0%)
# 2026-03-05 14:20 | rtk proxy git checkout   | 0 saved (0.0%)

​
Example 5: Compare Filtered vs Raw

# Save both outputs
rtk cargo build 2>&1 | tee filtered.txt
rtk proxy cargo build 2>&1 | tee raw.txt

# Compare differences
diff -u filtered.txt raw.txt
# Shows what RTK filter removed/modified

​
Comparison with Regular RTK Commands

AspectRegular RTKProxy Mode
Filtering✅ Smart filtering (60-90% reduction)❌ No filtering (raw output)
Token Savings✅ 60-90%❌ 0%
Tracking✅ Recorded with savings✅ Recorded with 0% savings
Compatibility⚠️ Only supported commands✅ Any command
Use CaseProduction workflowsDebugging, unsupported commands
Exit Codes✅ Preserved✅ Preserved
OutputCompressedUnchanged

​
Implementation Details

From RTK’s architecture:
  1. Command parsing: rtk proxy <command> is parsed by Clap
  2. Execution: RTK executes <command> directly via std::process::Command
  3. Output passthrough: stdout/stderr are passed unchanged to the terminal
  4. Tracking: Input and output tokens are the same (estimated from raw output)
  5. Exit code: Preserved from the underlying command
Proxy mode is essentially:
let output = Command::new(command).args(args).output()?;
stdout().write_all(&output.stdout)?;
stderr().write_all(&output.stderr)?;
std::process::exit(output.status.code().unwrap_or(1));
Tracking records:
  • original_cmd = <command> <args>
  • rtk_cmd = rtk proxy <command> <args>
  • input_tokens = output_tokens (no filtering)
  • saved_tokens = 0
  • savings_pct = 0.0

​
Troubleshooting

​
Proxy Mode Not Tracking

Symptom: rtk proxy <command> runs but doesn’t appear in rtk gain --history. Solution: Check database path and permissions. 
# Verify database location
echo $RTK_DB_PATH

# Check permissions
ls -la ~/.local/share/rtk/history.db

# Run with debug output
rtk proxy git status 2>&1 | grep -i track

​
Exit Code Not Preserved

Symptom: rtk proxy <command> always exits with 0, even on failure. Solution: This is a bug. Report at github.com/rtk-ai/rtk/issues. Workaround: 
# Use raw command directly
git status

​
Command Not Found

Symptom: rtk proxy terraform plan → “terraform: command not found” Solution: Proxy mode requires the underlying command to be in PATH. 
# Check command exists
which terraform

# If missing, install it
# Then retry proxy mode
rtk proxy terraform plan

​
See Also