pi-rtk-optimizer

RTK command rewriting and tool output compaction extension for the Pi coding agent.

pi-rtk-optimizer automatically rewrites bash tool commands to their rtk equivalents and compacts noisy tool output (bash, read, grep) to reduce context window usage while preserving actionable information for the AI agent.

Features

Command Rewriting

Automatic rewriting or suggestion-only mode for common development workflows
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
Search Grouping	Groups `grep`/`rg` results by file
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
Hard Truncation	Final character limit enforcement

Interactive Settings

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:

~/.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

pi install npm:pi-rtk-optimizer

Git Repository

pi install git:github.com/MasuRii/pi-rtk-optimizer

Usage

Settings Modal

Open the interactive settings modal:

/rtk

Use arrow keys to navigate settings, Enter 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:

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
`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.groupSearchOutput`	boolean	`true`	Group search results by file
`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.

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`	Also removes imports, keeps only signatures and key logic

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

{
  "enabled": true,
  "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,
    "groupSearchOutput": 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
├── config-store.ts         # Config load/save with normalization
├── config-modal.ts         # TUI settings modal and /rtk handler
├── command-rewriter.ts         # Command rewrite decision adapter for RTK delegation
├── rtk-rewrite-provider.ts     # Calls `rtk rewrite` as the rewrite source of truth
├── 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
├── runtime-guard.ts            # Runtime availability guard helpers for rewrite mode
├── output-compactor.ts         # Tool result compaction pipeline
├── output-metrics.ts           # Savings tracking and reporting
├── tool-execution-sanitizer.ts # Streaming bash execution output sanitizer
├── command-completions.ts      # /rtk subcommand completions
├── windows-command-helpers.ts  # Windows bash compatibility
└── techniques/                 # Compaction technique implementations
    ├── ansi.ts             # ANSI code stripping
    ├── build.ts            # Build output filtering
    ├── test-output.ts      # Test output aggregation
    ├── linter.ts           # Linter output aggregation
    ├── git.ts              # Git output compaction
    ├── search.ts           # Search result grouping
    ├── source.ts           # Source code filtering
    └── 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 <path> → cd "<normalized-path>" (converts backslashes)
Prepends PYTHONIOENCODING=utf-8 for Python commands

Dependencies

Peer dependencies: @mariozechner/pi-coding-agent, @mariozechner/pi-tui
Runtime: Node.js ≥20, optional rtk binary for command rewriting
Development verification: Node.js ≥20, npm, and Bun for the test scripts

Development

# Transpile-only TypeScript build check npm run build Full typecheck npm run typecheck Run Bun-based tests npm run test Full verification npm run check Bundle sanity check

npm run build:check

Credits

Inspired by:

Related Pi Extensions

pi-tool-display — Compact tool rendering and diff visualization
pi-permission-system — Permission enforcement for tool and command access
pi-smart-voice-notify — Multi-channel TTS and sound notifications
pi-image-tools — Image attachment and inline preview

NAME

SYNOPSIS

INFO

DESCRIPTION

README