The section landed in docs/TROUBLESHOOTING.md, a flat file removed in
a94e9493 when the docs were consolidated. Content there does not reach
the published guide, and the copy reintroduced install guidance that
develop had already pinned to --branch master.
Move the answer into docs/guide/resources/troubleshooting.md and drop the
duplicated Type Kit collision section, which that guide already covers.
The cache write/read breakdown is reported by `rtk cc-economics`, not by
`rtk gain`, so point readers at the command that actually shows it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The env-prefix stripper treated `sudo` like `env` / `VAR=val` and rewrote
`sudo docker ps` into `sudo rtk docker ps`. That breaks at runtime: `rtk`
lives in ~/.local/bin, which is not on sudo's secure_path, so the rewritten
command fails with "rtk: command not found" under root (reported in #146).
And where rtk *is* on secure_path, `sudo rtk` would run the whole rtk binary
as root — an unnecessary-privilege footgun.
Drop `sudo` from the env-prefix regex so sudo commands pass through
untouched. The permission verdict path is unaffected (it never used this
regex and already matches sudo commands as-is, e.g. `sudo:*` rules). env /
VAR= prefixes and transparent builtins (noglob, command, …) still rewrite
normally.
Verified: `sudo docker ps` / `sudo -u root docker ps` / `sudo noglob git
status` are no longer rewritten; `env FOO=bar docker ps`, `FOO=bar docker
ps`, `noglob git status` still are. fmt/clippy clean, full test suite green.
Refs #146
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Treat pre-existing extensions without ownership state as uncertain, cover project-scope aliases, clean canonical sidecars after symlink removal, and classify protected extension overwrites as breaking.
BREAKING CHANGE: non-interactive installs of modified or unrelated Pi/OMP extensions now require --auto-patch to approve overwrites.
`configuration.md` said an excluded tool "is covered however it is invoked".
The stated limits then covered only tools without their own filter, and exactness
— leaving three invocation forms of *filtered* tools promised but not delivered.
Scope the sentence to the wrapper, interpreter and path spellings that are
actually peeled, and table the three that are not, each with its cause:
- `head -20 f` / `tail -n 5 f` — the line-range fast path returns before the
exclusion is consulted (#2823); `head f` is excluded normally
- `gradlew.bat build` / `mvnw.cmd test` — path stripping splits on `/`, so a
`.bat`/`.cmd` spelling never reduces to the tool name (#3617)
- `golangci run ./...` — `golangci run` is one of the rule's own aliases and is
kept whole, so it misses a `golangci-lint` entry
Each row verified against a build on `develop` at e533c40, including the
documented workaround: `["golangci"]` excludes the alias form but not
`golangci-lint run`, so both entries are needed.
Docs only, no behaviour change.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`exclude_commands` entries name a tool, but a command can spell that tool with a
wrapper (`npx playwright test`), an interpreter (`python3 -m pytest tests/`) or a
path (`vendor/bin/phpunit tests/`). Those spellings are absorbed by each rule's own
pattern rather than stripped beforehand, so the anchored `^playwright($|\s)` never
matched and the exclusion silently did nothing — the README shipped
`exclude_commands = ["curl", "playwright"]` as the example, and `playwright` is a
tool almost nobody invokes bare.
Peel the wrapper off the command and match what remains, alongside the existing
check on the typed command. The peeled form keeps the arguments, so an anchored
entry still narrows the way it was written: `"^ls$"` excludes a bare `ls` without
swallowing `ls -la`.
Peeling uses the rule's own `rewrite_prefixes`, taking the shortest token-suffix of
the matched prefix that is itself a prefix of that rule. That drops `npx` and
`python3 -m` while keeping a subcommand the rule treats as part of the tool, so
`golangci-lint run` does not collapse to `run`.
Peeling reuses the PHP normalization the rewrite path already applies (`php`
wrapper and ini flags, leading `./`, vendor/composer bin dir), extracted into
`php_tool_form` and shared by both, so `php vendor/bin/phpunit tests/` is excluded
by `["phpunit"]` the same way `vendor/bin/phpunit tests/` is.
The peeled check is gated on a non-empty `exclude_commands`, keeping the default
config off the `RULES` scan on the hook rewrite path.
Matching the resolved `rtk` target instead would have been shorter but wrong in
both directions: it misses tools whose target differs from the binary (`["eslint"]`
would still rewrite `npx eslint .`, since the target is `lint`), and it leaks
across tools sharing a target (`["read"]` would exclude `cat`, `["git"]` would
exclude `yadm`). Peeling has neither failure.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Add `--agent omp` to `rtk init` (with `-g`, `--uninstall`, `--show`)
for the Oh My Pi coding agent (https://github.com/can1357/oh-my-pi).
OMP loads the same `hooks/pi/rtk.ts` extension via its built-in
legacy-pi-compat layer, which remaps the Pi package imports to OMP's
bundled equivalent — so no separate OMP implementation is needed and
the rewrite behavior stays byte-identical (mutualization).
- Local scope: <project>/.omp/extensions/rtk.ts
- Global scope: ~/.omp/agent/extensions/rtk.ts
- `--uninstall` is three-way safe: missing → no-op, stock content →
removed, modified RTK content → bail with manual-removal guidance
- `--show` reports both scopes (installed / stock / modified / absent)
Co-authored-by: makoMakoGo <makoMakoGo@users.noreply.github.com>
Addresses @aeppling's review on #3391:
Blocking fixes:
- run_vibe now returns Ok(()) on malformed JSON (matches run_droid /
run_copilot / run_cursor pattern). Prior code violated the exit-code
contract documented at src/hooks/README.md:100 — a bad payload exited
non-zero and blocked the agent's command. Fixed via a match on
serde_json::from_str with a stderr warning fallback.
- Extract run_vibe_inner(input: &str) -> Option<String> from run_vibe so
the hook contract is unit-testable (mirrors run_droid_inner). Public
run_vibe becomes a thin stdin/stdout wrapper.
- Add 6 runtime tests exercising the hook contract: bash rewrite happy
path, non-bash tool passthrough, empty command passthrough, malformed
JSON returns None, unknown binary passthrough, substitution defers.
Should-fix:
- Telemetry agent detection: add ~/.vibe/hooks.toml to detect_hook_type()
checks in src/core/telemetry.rs, plus the two test enum arrays so Vibe
sessions no longer report as 'unknown' in rtk gain history.
- Dead deny arm: add a comment on Host::Vibe in permissions.rs
documenting that the empty-rules branch is defensive scaffolding for
when Vibe ships native denylist/allowlist config we can honor.
- Broken link: patch_vibe_hooks_toml skip-message now points at
https://www.rtk-ai.app/guide/getting-started/supported-agents#mistral-vibe
instead of a fragment that doesn't resolve.
Nits addressed:
- Install summary no longer prints 'hook installed' when the user chose
PatchMode::Skip or declined the interactive prompt. patch_vibe_hooks_toml
now returns a VibeHookPatchOutcome enum (Installed / AlreadyPresent /
Skipped) and the caller gates the summary on it.
- Document the string-spacing tradeoff on vibe_hooks_toml_has_rtk: a
reformatted 'name="rtk-rewrite"' would defeat idempotency, acceptable
because we control the writer and toml_edit round-trip would clobber
user comments.
- Fix stale line in src/hooks/README.md 'Adding New Functionality':
hook_check.rs::maybe_warn() only checks the Claude Code hook now,
not every agent.
Documentation:
- docs/guide/getting-started/supported-agents.md: frontmatter now lists
Mistral Vibe, drop 'planned' from the intro, tier table row flipped
from 'Planned (#800)' to 'Rust binary (pre_tool) / Yes', replace the
### Mistral Vibe (planned) placeholder with a full user-facing section
modeled on Factory Droid (install/uninstall commands, hook mechanism,
permission semantics, idempotency contract).
- hooks/README.md: agent count 9 -> 10, add Vibe entry to Directory
Structure list, add Vibe row to Supported Agents table, add
'### Mistral Vibe (Rust Binary)' entry to the JSON Formats section
showing the pre_tool input shape and rewrite response shape.
- src/hooks/README.md: agent count 5 -> 6, add Vibe row to per-host
ask-support table.
- README.md: '15 AI coding tools' -> '16'.
No behavior change for existing agents.
rtk init --copilot registered both a PascalCase PreToolUse entry and a
camelCase preToolUse entry in the same rtk-rewrite.json, on the assumption
that VS Code Copilot Chat needs the former and Copilot CLI needs the latter.
Live testing showed Copilot CLI treats PreToolUse/preToolUse as two
independent, sequentially-run hooks — a redundant second `rtk hook copilot`
process spawn per tool call, chaining the first hook's rewrite into the
second's input (confirmed via raw stdin capture, and confirmed independent
of declaration order in the file). Also confirmed Copilot CLI honors the
PascalCase-only schema perfectly well on its own, receiving the same
tool_name/tool_input.command shape either way — so the camelCase entry buys
nothing for Copilot CLI, while adding process overhead and an extra,
harder-to-reason-about execution path.
Drop the camelCase preToolUse entry, keeping the single PascalCase
PreToolUse entry shared by both hosts. Existing installs are not upgraded
automatically — re-running `rtk init --copilot` / `rtk init --global
--copilot` overwrites the old dual-schema file with the new one
(write_if_changed overwrites unconditionally on content diff), verified
by test_copilot_init_upgrades_old_dual_schema_install and
test_copilot_global_install_upgrades_old_dual_schema_install, which seed
the old dual-schema content and assert it gets replaced.
The tree was copied into 11 files, so every future correction to it meant
11 edits in 7 languages. It now lives only in savings-explained.md, which
each of those pages already links to.
The surrounding prose stays: it carries the dilution point in the reader's
own language, which is the part that matters at a glance. Three pages
introduced the diagram with a trailing colon, reflowed into the following
paragraph. TRACKING.md gained the link it was missing.
Restore to develop the files where the rescoping added noise without
helping a reader: all of .claude/, the src/ module READMEs that only
described their own filters, ARCHITECTURE.md, TELEMETRY.md, quick-start,
configuration and troubleshooting.
Also drop the "Two estimators, one caveat" table from savings-explained.md.
The page already states that rtk gain estimates bytes/4 and ships no
tokenizer; enumerating the test-side estimator was detail no reader needs.
The user-facing surface keeps the rescoping: READMEs in seven languages,
the guide, hooks, and the analytics and usage pages.
The arrow diagram read as a pipeline where bash output becomes input tokens
which become cost. The real relationship is containment: bash output is
part of input tokens, and input tokens are part of cost alongside output
tokens.
Replace the arrow chain with a tree in all 12 places it appeared, including
the six translated READMEs:
Cost
├─ Input tokens
│ ├─ Bash output <- the only part RTK filters
│ ├─ Your prompt
│ ├─ System prompt
│ └─ Conversation history
└─ Output tokens <- what the model writes
This also makes the dilution self-evident: RTK shrinks one leaf, so the
effect on the root is bounded by that leaf's share.
The documented release blocker was ">=60% savings", but the code never
enforced that. 23 of the 63 threshold assertions in src/ already sit below
60% (15, 20, 30, 40 and 50% appear across aws, gh, git, glab and mvn), so
the gate was aspirational rather than real.
Set the floor to 20%, pointing at the existing "Correctness VS Token
Savings" section for the reasoning rather than restating it: a modest, safe
reduction beats an aggressive one that drops information the agent needed.
Descriptive "60-90%" ranges are left alone where they report what filters
actually achieve. Only requirement statements moved to the 20% floor.
Also reduce links to savings-explained.md down to one per file, and only
from root docs and user-facing pages. Removed from docs/contributing/ and
.claude/rules/, where the surrounding text already carries the caveat.
RTK was documented as delivering "60-90% token savings", which reads as a
cost reduction. What RTK actually reduces is bash output bytes. Those are
one contributor to input tokens, which are themselves only part of a bill
that also counts output tokens, so the reduction dilutes at every step.
- add docs/guide/resources/savings-explained.md as the canonical explainer:
the savings chain, both estimators, and what RTK does not reduce
- rescope the headline claim across README (7 languages), the guide, hook
rules, agent definitions and module READMEs
- relabel per-command tables as bash output reduction, keeping every figure
- document that reported tokens are estimates: rtk gain uses bytes/4
(src/core/tracking.rs), filter tests use split_whitespace().count().
Neither is a real tokenizer, so ratios hold but absolute counts do not
Remove figures that had no source: the $3/Mtok constant and its $36
example, the +/-10% tokenization accuracy claim, the 99.5% hook-install
figure, the invented session tables in README and INSTALL, and the 30-50%
parser range.
CHANGELOG is untouched. Shipped release notes stay as a historical record.
Drop the hardcoded mirrors of Droid's built-in command lists and stop
emitting permissionDecision entirely. RTK now steps aside only on
explicit commandDenylist/commandBlocklist entries, unioned across all
four settings scopes (user + project, settings.json +
settings.local.json); every other command is rewritten via updatedInput
and the decision is left to Droid's native flow.
Verified against Droid CLI 0.153.1: updatedInput is applied after
Droid's own permission evaluation of the original command, so native
allowlist decisions are unaffected and deny entries fire natively.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SpSp3Arj7fG1XJYhXoCMGC
Propagates the README Droid documentation to
docs/guide/getting-started/supported-agents.md per review feedback:
frontmatter description, agents table row, and an installation section
covering hooks.json placement and Droid-native permission handling.
Claude-Session: https://claude.ai/code/session_015CvKLxKMnmcvwY5CjHVTF5
Adrien Eppling