Feature: filter transparency header + better rtk proxy documentation
#622 创建于 2026年3月16日
描述
Problem
When RTK filters output, there's no signal to Claude or the user about what transformation was applied. When a response looks wrong, it's impossible to tell if it's a filter bug, a hallucination, or real command output.
Additionally, rtk proxy <cmd> exists as an escape hatch but is not documented in README or CLAUDE.md, so neither users nor LLMs know to reach for it.
Proposed fix
1. Optional filter transparency header
Add an opt-in first-line header showing which filter was applied and how much was removed:
[rtk: git-log filter applied, 84% reduction — use `rtk proxy git log` for full output]
Activation: RTK_SHOW_FILTER=1 env var or show_filter = true in ~/.config/rtk/config.toml.
Off by default to keep output clean.
2. Document rtk proxy prominently
Add to README under "Escape hatches":
- What it does (bypass filtering, track usage)
- When to use it (filter bug, debugging, edge case)
- Example:
rtk proxy git log --oneline -20
Add the same to CLAUDE.md so LLMs know this option exists.
Why this matters
RTK's credibility depends on predictable, diagnosable behavior. When something looks off, developers (and LLMs) need a clear path to verify: "is this the filter or reality?" Right now that path doesn't exist.
Acceptance criteria
RTK_SHOW_FILTER=1 rtk git log -10prints a one-line header before the filtered output- Header format is machine-readable (structured, no prose)
rtk proxyis documented in README with examplesrtk proxyis referenced in CLAUDE.md escape hatch section