Loaded through the root pi-ext package.
See ../../README.md.
Requires rtk >= 0.23.0 on PATH.
If missing or old, the extension prints one warning and stays idle.
Commands / tools / settings
Pi commands:
none.
Pi tools:
none.
Pi hooks:
tool_call:
watches builtin bash calls and may replace input.command with rtk rewrite output.
Pi settings:
rtk.rewriteTimeoutMs:
timeout in milliseconds for rtk rewrite and the rtk --version probe.
Env var PI_RTK_REWRITE_TIMEOUT_MS.
Default 2000.
Valid values are integers from 1 to 2147483647.
Precedence: env var, trusted project .pi/settings.json, user ~/.pi/agent/settings.json, default.
Project settings are ignored until the project is trusted.
The value is resolved once per session at session start.
An invalid value never falls through to a lower source.
It produces one warning naming the source and the default 2000 is used.
Env vars:
PI_RTK_REWRITE_TIMEOUT_MS=5000
RTK_DISABLED=1
Prefix one command with RTK_DISABLED=1 to bypass rewriting.
UI
The bash tool widget is the command indicator.
When RTK applies, Pi shows the rewritten rtk ... command.
After session start, Pi checks RTK in the background and warns if it is unavailable or too old.
The first bash call waits for that shared check when it is still running.
Behavior
rtk does one thing:
registers the bash hook without blocking extension load
probes rtk --version after session start, or on the first bash call
warns once and leaves commands unchanged if rtk is missing or too old
ignores non-bash tools
ignores empty, already-rtk, and disabled commands
calls rtk rewrite <command> with rtk.rewriteTimeoutMs timeout (default 2s)
applies exit 0 and 3 rewrites
caches exact successful rewrites for the current session
locally maps missing journalctl, systemctl status, hyprctl clients, and ps filters to rtk summary
leaves other exit 1, exit 2, timeouts, errors, and empty output untouched
Performance
rtk rewrite starts an external process, so repeated exact commands reuse deterministic successful results within one session.
Session transitions clear the cache, and no-match or transient failures remain retryable.
mise run //extensions/rtk:bench compares repeated commands against unique-command controls through Pi's test harness and installed RTK executable.
mise run //extensions/rtk:profile records a Node CPU profile under .research/rtk.
mise run //extensions/rtk:benchstat <baseline> <candidate> performs statistical comparison.
No prompt injection.
No status widget.
No command gating.
No output compaction.
No shell-specific helpers.
Debug
Opt in through debug configuration.
Safe events: session.start, session.shutdown, rtk.status.start, rtk.status.finish.
# rtk
Rewrites Pi `bash` tool calls through RTK.
## Install / load
Loaded through the root `pi-ext` package.
See [../../README.md](../../README.md).
Requires `rtk >= 0.23.0` on `PATH`.
If missing or old, the extension prints one warning and stays idle.
## Commands / tools / settings
Pi commands:
none.
Pi tools:
none.
Pi hooks:
- `tool_call`:
watches builtin `bash` calls and may replace `input.command` with `rtk rewrite` output.
Pi settings:
- `rtk.rewriteTimeoutMs`:
timeout in milliseconds for `rtk rewrite` and the `rtk --version` probe.
Env var `PI_RTK_REWRITE_TIMEOUT_MS`.
Default `2000`.
Valid values are integers from `1` to `2147483647`.
Precedence: env var, trusted project `.pi/settings.json`, user `~/.pi/agent/settings.json`, default.
Project settings are ignored until the project is trusted.
The value is resolved once per session at session start.
An invalid value never falls through to a lower source.
It produces one warning naming the source and the default `2000` is used.
Env vars:
```text
PI_RTK_REWRITE_TIMEOUT_MS=5000
RTK_DISABLED=1
```
Prefix one command with `RTK_DISABLED=1` to bypass rewriting.
## UI
The bash tool widget is the command indicator.
When RTK applies, Pi shows the rewritten `rtk ...` command.
After session start, Pi checks RTK in the background and warns if it is unavailable or too old.
The first `bash` call waits for that shared check when it is still running.
## Behavior
`rtk` does one thing:
1. registers the `bash` hook without blocking extension load
2. probes `rtk --version` after session start, or on the first `bash` call
3. warns once and leaves commands unchanged if `rtk` is missing or too old
4. ignores non-bash tools
5. ignores empty, already-`rtk`, and disabled commands
6. calls `rtk rewrite <command>` with `rtk.rewriteTimeoutMs` timeout (default 2s)
7. applies exit `0` and `3` rewrites
8. caches exact successful rewrites for the current session
9. locally maps missing `journalctl`, `systemctl status`, `hyprctl clients`, and `ps` filters to `rtk summary`
10. leaves other exit `1`, exit `2`, timeouts, errors, and empty output untouched
## Performance
`rtk rewrite` starts an external process, so repeated exact commands reuse deterministic successful results within one session.
Session transitions clear the cache, and no-match or transient failures remain retryable.
`mise run //extensions/rtk:bench` compares repeated commands against unique-command controls through Pi's test harness and installed RTK executable.
`mise run //extensions/rtk:profile` records a Node CPU profile under `.research/rtk`.
`mise run //extensions/rtk:benchstat <baseline> <candidate>` performs statistical comparison.
No prompt injection.
No status widget.
No command gating.
No output compaction.
No shell-specific helpers.
## Debug
Opt in through [debug configuration](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, `rtk.status.start`, `rtk.status.finish`.