# pi-rtk-optimizer [![npm version](https://img.shields.io/npm/v/pi-rtk-optimizer?style=for-the-badge)](https://www.npmjs.com/package/pi-rtk-optimizer) [![License](https://img.shields.io/github/license/MasuRii/pi-rtk-optimizer?style=for-the-badge)](LICENSE) [![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=for-the-badge)]() [![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/Y8Y01PSSVR) > Optional RTK command rewriting and non-search tool output compaction for the Pi coding agent. image **pi-rtk-optimizer** compacts noisy `bash` and `read` output. RTK CLI command rewriting is available but disabled by default, and search tool output is deliberately left to FFF.
## Features ### Command Rewriting - Optional **automatic rewriting** or **suggestion-only** mode for common development workflows (disabled by default) - Delegates bash command rewrite decisions to the installed `rtk rewrite` command, keeping RTK as the source of truth for supported commands, shell parsing, bypasses, and compound-command behavior - Runtime guard when `rtk` binary is unavailable (raw commands run unchanged and repeated missing-binary rewrite probes are avoided) - `/rtk show` and `/rtk verify` surface the resolved `rtk` executable path when the host can resolve it - Pi-specific shell safety fixups for rewritten commands on Windows ### Output Compaction Pipeline Multi-stage pipeline to reduce token consumption: | Stage | Description | |-------|-------------| | ANSI Stripping | Removes terminal color/formatting codes | | Test Aggregation | Summarizes test runner output (pass/fail counts) | | Build Filtering | Extracts errors/warnings from build output | | Git Compaction | Condenses `git status`, `git log`, `git diff` output | | Linter Aggregation | Summarizes linting tool output | | Source Code Filtering | `none`, `minimal`, or `aggressive` comment/whitespace removal with userscript metadata preservation | | Smart Truncation | Preserves file boundaries and important lines while keeping 80-line reads exact | | Anchor-Safe Read Compaction | Detects hashline/anchored `read` output and preserves complete edit anchors when filtering or truncating anchored lines | | Hard Truncation | Final character limit enforcement | Bash output compaction applies to both the local `bash` tool and `pi-ssh`'s `ssh_bash` output alias. This only sanitizes/compacts returned text: RTK never rewrites remote commands. Structured remote search results from `ssh_find` and `ssh_grep`, and exact remote file reads from `ssh_read`, remain outside RTK processing. ### Interactive Settings - Tabbed TUI settings modal via `/rtk` command - Real-time configuration changes without restart - Command completions for all subcommands ### Session Metrics - Tracks compaction savings per tool type - View statistics with `/rtk stats` ## Installation ### Local Extension Folder Place this folder in one of the following locations: ```text ~/.pi/agent/extensions/pi-rtk-optimizer # Global default (when PI_CODING_AGENT_DIR is unset) $PI_CODING_AGENT_DIR/extensions/pi-rtk-optimizer # Global when PI_CODING_AGENT_DIR is set .pi/extensions/pi-rtk-optimizer # Project-specific ``` Pi auto-discovers extensions in these paths on startup. ### npm Package ```bash pi install npm:pi-rtk-optimizer ``` ### Git Repository ```bash pi install git:github.com/MasuRii/pi-rtk-optimizer ``` ## Usage ### Settings Modal Open the interactive settings modal: ``` /rtk ``` Use ←/→ to switch tabs, ↑/↓ to navigate settings in the active tab, type to search, Enter/Space to cycle values, and Escape to close. ### Subcommands | Command | Description | |---------|-------------| | `/rtk` | Open settings modal | | `/rtk show` | Display current configuration and runtime status | | `/rtk path` | Show config file path | | `/rtk verify` | Check if `rtk` binary is available | | `/rtk stats` | Show output compaction metrics for current session | | `/rtk clear-stats` | Reset compaction metrics | | `/rtk reset` | Reset all settings to defaults | | `/rtk help` | Display usage help | ## Configuration Configuration is stored at: ```text Default global path: ~/.pi/agent/extensions/pi-rtk-optimizer/config.json Actual global path: $PI_CODING_AGENT_DIR/extensions/pi-rtk-optimizer/config.json when PI_CODING_AGENT_DIR is set ``` A starter template is included at `config/config.example.json`. For audit or debugging sessions, keep `showRewriteNotifications` enabled and disable lossy `read` compaction/source filtering before gathering evidence. Existing `config.json` files are user-owned runtime state; do not overwrite local choices unless you intentionally want to change live extension behavior. ### Configuration Options #### Top-Level Settings | Option | Type | Default | Description | |--------|------|---------|-------------| | `enabled` | boolean | `true` | Master switch for all extension features | | `commandRewritingEnabled` | boolean | `false` | Enable optional RTK CLI command rewriting | | `mode` | string | `"rewrite"` | `"rewrite"` (auto-rewrite) or `"suggest"` (notify only) | | `guardWhenRtkMissing` | boolean | `true` | Run original commands when rtk binary unavailable | | `showRewriteNotifications` | boolean | `true` | Show rewrite notices in TUI | #### Rewrite Source Bash command support is intentionally resolved by the installed `rtk` binary through `rtk rewrite`. The extension does not maintain duplicate rewrite rules or category classifiers; update/configure RTK itself for command support policy. > **Breaking in 0.6.0:** Rewrite category toggles (`rewriteGitGithub`, `rewriteFilesystem`, `rewriteRust`, `rewriteJavaScript`, `rewritePython`, `rewriteGo`, `rewriteContainers`, `rewriteNetwork`, and `rewritePackageManagers`) were removed from the extension config surface. Existing rewrite policy should be configured in RTK because the extension now delegates rewrite ownership to `rtk rewrite`. #### Output Compaction Settings | Option | Type | Default | Description | |--------|------|---------|-------------| | `outputCompaction.enabled` | boolean | `true` | Enable output compaction pipeline | | `outputCompaction.stripAnsi` | boolean | `true` | Remove ANSI escape codes | | `outputCompaction.readCompaction.enabled` | boolean | `false` | Enable lossy compaction for `read` output; defaults off so code reads stay exact | | `outputCompaction.sourceCodeFilteringEnabled` | boolean | `false` | Enable source code filtering for `read` output when read compaction is enabled | | `outputCompaction.preserveExactSkillReads` | boolean | `false` | Keep reads under configured Pi/global/project skill directories exact, bypassing read compaction | | `outputCompaction.sourceCodeFiltering` | string | `"none"` | Filter level: `"none"`, `"minimal"`, `"aggressive"` | | `outputCompaction.aggregateTestOutput` | boolean | `true` | Summarize test runner output | | `outputCompaction.filterBuildOutput` | boolean | `true` | Filter build/compile output | | `outputCompaction.compactGitOutput` | boolean | `true` | Compact git command output | | `outputCompaction.aggregateLinterOutput` | boolean | `true` | Summarize linter output | | `outputCompaction.trackSavings` | boolean | `true` | Track compaction metrics | Skill-read preservation covers the global Pi skills directory (`~/.pi/agent/skills` by default, or `$PI_CODING_AGENT_DIR/skills` when set), `~/.agents/skills`, project `.pi/skills`, and ancestor `.agents/skills` directories. When `read` output uses Pi hashline/anchor prefixes, the compactor treats each anchored line as an indivisible edit anchor. Source filtering and truncation may omit anchored lines, but retained lines keep their complete anchor prefixes; hard truncation inserts an anchor-safe marker instead of cutting through an anchor. #### Truncation Settings | Option | Type | Default | Range | Description | |--------|------|---------|-------|-------------| | `outputCompaction.smartTruncate.enabled` | boolean | `false` | — | Enable smart line-based truncation for read output when read compaction is enabled | | `outputCompaction.smartTruncate.maxLines` | number | `220` | 40–4000 | Maximum lines after smart truncation | | `outputCompaction.truncate.enabled` | boolean | `true` | — | Enable hard character truncation | | `outputCompaction.truncate.maxChars` | number | `12000` | 1000–200000 | Maximum characters in final output | ### Source Code Filtering Levels | Level | Behavior | |-------|----------| | `none` | No filtering applied | | `minimal` | Removes non-doc comments, collapses blank lines | | `aggressive` | Keeps imports, constants, and signatures while replacing implementation details | > **Note:** When read compaction, source filtering, and read truncation safeguards are active, Pi injects a troubleshooting note for repeated file-edit mismatches. If edits fail because "old text does not match," disable read compaction via `/rtk`, re-read the file, apply the edit, then re-enable compaction. ### Example Configuration ```json { "enabled": true, "commandRewritingEnabled": false, "mode": "rewrite", "guardWhenRtkMissing": true, "showRewriteNotifications": true, "outputCompaction": { "enabled": true, "stripAnsi": true, "readCompaction": { "enabled": false }, "sourceCodeFilteringEnabled": false, "preserveExactSkillReads": false, "sourceCodeFiltering": "none", "aggregateTestOutput": true, "filterBuildOutput": true, "compactGitOutput": true, "aggregateLinterOutput": true, "trackSavings": true, "smartTruncate": { "enabled": false, "maxLines": 220 }, "truncate": { "enabled": true, "maxChars": 12000 } } } ``` ## Technical Details ### Architecture ``` index.ts # Pi auto-discovery entrypoint src/ ├── index.ts # Extension bootstrap and event wiring ├── command-register.ts # Lazy /rtk command registration ├── command-completions.ts # /rtk subcommand completions ├── command-rewriter.ts # Command rewrite decision adapter for RTK delegation ├── rtk-rewrite-provider.ts # Calls `rtk rewrite` as the rewrite source of truth ├── rtk-executable-resolver.ts # Cross-platform rtk executable discovery ├── runtime-guard.ts # Runtime availability guard helpers for rewrite mode ├── rewrite-pipeline-safety.ts # Shell-safety fixups for rewritten commands ├── rtk-command-environment.ts # RTK_DB_PATH scoping for rewritten commands ├── shell-env-prefix.ts # Environment assignment parsing helpers ├── windows-command-helpers.ts # Windows bash compatibility ├── output-compactor.ts # Tool result compaction pipeline ├── output-metrics.ts # Savings tracking and reporting ├── tool-execution-sanitizer.ts # Streaming bash execution output sanitizer ├── config-store.ts # Config load/save with normalization ├── config-modal.ts # TUI settings modal and /rtk handler ├── boolean-format.ts # Boolean display helpers ├── constants.ts # Shared extension constants ├── record-utils.ts # Record/object guards ├── types.ts # Shared config/runtime types ├── types-shims.d.ts # Ambient Pi package shims for local typecheck ├── zellij-modal.ts # Vendored modal renderer used by settings UI └── techniques/ # Compaction technique implementations ├── ansi.ts # ANSI code stripping ├── build.ts # Build output filtering ├── command-detection.ts # Tool command detection helpers ├── git.ts # Git output compaction ├── index.ts # Technique re-export surface ├── linter.ts # Linter output aggregation ├── path-utils.ts # Cross-platform path shortening ├── search.ts # Search result grouping ├── source.ts # Source code filtering ├── test-output.ts # Test output aggregation └── truncate.ts # Smart and hard truncation ``` ### Event Hooks The extension hooks into Pi's event system: - **`tool_call`** — Rewrites bash commands to rtk equivalents or emits suggestions - **`tool_result`** — Compacts completed tool output before context consumption - **`tool_execution_start` / `tool_execution_update` / `tool_execution_end`** — Tracks and sanitizes streamed bash output - **`before_agent_start`** — Conditionally injects source-filter troubleshooting guidance - **`session_start` / `agent_end`** — Refreshes config and clears in-session tracking state - **Registered `/rtk` command** — Handles settings, status, verification, stats, and reset subcommands ### Windows Compatibility Automatic fixes applied on Windows: - `cd /d ` → `cd ""` (converts backslashes) - Prepends `PYTHONIOENCODING=utf-8` for Python commands ### Dependencies - **Peer dependencies:** `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui` - **Runtime:** Node.js ≥20, optional `rtk` binary for command rewriting - **Development verification:** Node.js ≥24 and npm for Node/tsx test scripts using Node's experimental test module mocks ## Development ```bash # Transpile-only TypeScript build check npm run build # Full typecheck npm run typecheck # Run Node/tsx tests npm run test # Full verification npm run check # Bundle sanity check npm run build:check ``` ## Credits Inspired by: - [mcowger/pi-rtk](https://github.com/mcowger/pi-rtk) - [rtk-ai/rtk](https://github.com/rtk-ai/rtk) ## Related Pi Extensions - [pi-tool-display](https://github.com/MasuRii/pi-tool-display) — Compact tool rendering and diff visualization - [pi-permission-system](https://github.com/MasuRii/pi-permission-system) — Permission enforcement for tool and command access - [pi-smart-voice-notify](https://github.com/MasuRii/pi-smart-voice-notify) — Multi-channel TTS and sound notifications - [pi-image-tools](https://github.com/MasuRii/pi-image-tools) — Image attachment and inline preview ## License [MIT](LICENSE) © MasuRii