my-pi/pi-rtk-optimizer/README.md

pi-rtk-optimizer

Optional RTK command rewriting and non-search tool output compaction for the Pi coding agent. 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:

~/.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 ←/→ 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 read from — and /rtk saves to — the installed bundle's config/rtk-optimizer.json (the bundle repository's config/ directory is the single source of truth; pi update refreshes the installed copy). Nothing is deployed to or migrated from the agent directory.

For audit or debugging sessions, keep showRewriteNotifications enabled and disable lossy read compaction/source filtering before gathering evidence. Edit config/rtk-optimizer.json in the bundle repository for durable changes; pi update overwrites the installed copy on upgrade.

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	false	—	Enable hard character truncation (off in this bundle — pi-overflow owns display 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

{
  "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": false,
      "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 <path> → cd "<normalized-path>" (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

# 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
• rtk-ai/rtk

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

License

MIT © MasuRii