pi-rtk-optimizer 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-03-04
+
+### Changed
+- Rewrote README.md with professional documentation standards
+- Added comprehensive feature documentation, configuration reference, and usage examples
+
 ## [0.3.0] - 2026-03-02
 
 ### Changed

package/README.md

@@ -1,42 +1,75 @@
 # pi-rtk-optimizer
 
-RTK rewrite + output compaction extension for the Pi coding agent.
-
-`pi-rtk-optimizer` rewrites supported `bash` tool commands to `rtk` equivalents and compacts noisy `tool_result` output (`bash`, `read`, `grep`) to reduce context/token usage while preserving actionable information.
+> RTK command rewriting and tool output compaction extension for the Pi coding agent.
 
 ![background](asset/pi-rtk-optimizer-background.png)
 
+**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 rewrite/suggestion mode for common dev workflows (`git`, `gh`, `cargo`, `npm`, `pytest`, `go`, `docker`, etc.)
-- Runtime guard when `rtk` binary is unavailable
-- Output compaction pipeline:
-  - ANSI stripping
-  - build/test/linter/git/search summarization
-  - source-code filtering (`none`, `minimal`, `aggressive`)
-  - smart truncation + hard truncation
-- Interactive TUI settings modal via `/rtk`
-- `/rtk` command completions and utility subcommands (`show`, `verify`, `stats`, `reset`, ...)
-- Session metrics for compaction savings
+### Command Rewriting
+
+- **Automatic rewriting** or **suggestion-only** mode for common development workflows
+- Supported command categories:
+  - **Git/GitHub** — `git`, `gh` commands
+  - **Filesystem** — `cat`, `head`, `tail`, `grep`, `rg`, `ls`, `tree`, `find`, `diff`, `wc`, `bash`, `cmd`, `powershell`
+  - **Rust** — `cargo` commands
+  - **JavaScript** — `vitest`, `npm`, `yarn`, `pnpm`, `bun` commands
+  - **Python** — `pytest`, `python`, `pip`, `uv` commands
+  - **Go** — `go` commands
+  - **Containers** — `docker`, `docker-compose`, `podman` commands
+  - **Network** — `curl`, `wget` commands
+  - **Package Managers** — `apt`, `brew`, `dnf`, `pacman`, `yum` commands
+- Runtime guard when `rtk` binary is unavailable (falls back to original commands)
+
+### 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 |
+| Smart Truncation | Preserves file boundaries and important lines |
+| 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
+### Local Extension Folder
 
-Place this folder in:
+Place this folder in one of the following locations:
 
-- Global: `~/.pi/agent/extensions/pi-rtk-optimizer`
-- Project: `.pi/extensions/pi-rtk-optimizer`
+```
+~/.pi/agent/extensions/pi-rtk-optimizer     # Global (all projects)
+.pi/extensions/pi-rtk-optimizer              # Project-specific
+```
 
-Pi auto-discovers these paths.
+Pi auto-discovers extensions in these paths on startup.
 
-### As an npm package
+### npm Package
 
 ```bash
 pi install npm:pi-rtk-optimizer
 ```
 
-Or from git:
+### Git Repository
 
 ```bash
 pi install git:github.com/MasuRii/pi-rtk-optimizer
@@ -44,71 +77,207 @@ pi install git:github.com/MasuRii/pi-rtk-optimizer
 
 ## Usage
 
-Open settings modal:
+### Settings Modal
+
+Open the interactive settings modal:
 
-```text
+```
 /rtk
 ```
 
-Subcommands:
+Use arrow keys to navigate settings, Enter to cycle values, and Escape to close.
 
-```text
-/rtk show
-/rtk path
-/rtk verify
-/rtk stats
-/rtk clear-stats
-/rtk reset
-/rtk help
-```
+### 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
 
-Runtime config is stored at:
+Configuration is stored at:
 
-```text
+```
 ~/.pi/agent/extensions/pi-rtk-optimizer/config.json
 ```
 
-A starter file is included as:
+A starter template is included at `config/config.example.json`.
+
+### 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 Category Toggles
+
+| Option | Default | Commands Affected |
+|--------|---------|-------------------|
+| `rewriteGitGithub` | `true` | `git`, `gh` |
+| `rewriteFilesystem` | `true` | `cat`, `head`, `tail`, `grep`, `rg`, `ls`, `tree`, `find`, `diff`, `wc` |
+| `rewriteRust` | `true` | `cargo` |
+| `rewriteJavaScript` | `true` | `vitest`, `npm`, `yarn`, `pnpm`, `bun` |
+| `rewritePython` | `true` | `pytest`, `python`, `pip`, `uv` |
+| `rewriteGo` | `true` | `go` |
+| `rewriteContainers` | `true` | `docker`, `docker-compose`, `podman` |
+| `rewriteNetwork` | `true` | `curl`, `wget` |
+| `rewritePackageManagers` | `true` | `apt`, `brew`, `dnf`, `pacman`, `yum` |
+
+#### Output Compaction Settings
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `outputCompaction.enabled` | boolean | `true` | Enable output compaction pipeline |
+| `outputCompaction.stripAnsi` | boolean | `true` | Remove ANSI escape codes |
+| `outputCompaction.sourceCodeFilteringEnabled` | boolean | `true` | Enable source code filtering for `read` output |
+| `outputCompaction.sourceCodeFiltering` | string | `"minimal"` | 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 |
+
+#### Truncation Settings
+
+| Option | Type | Default | Range | Description |
+|--------|------|---------|-------|-------------|
+| `outputCompaction.smartTruncate.enabled` | boolean | `true` | — | Enable smart line-based truncation |
+| `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:** If file edits fail because "old text does not match," disable source filtering via `/rtk`, re-read the file, apply the edit, then re-enable filtering.
+
+### Example Configuration
+
+```json
+{
+  "enabled": true,
+  "mode": "rewrite",
+  "guardWhenRtkMissing": true,
+  "showRewriteNotifications": true,
+  "rewriteGitGithub": true,
+  "rewriteFilesystem": true,
+  "rewriteRust": true,
+  "rewriteJavaScript": true,
+  "rewritePython": true,
+  "rewriteGo": true,
+  "rewriteContainers": true,
+  "rewriteNetwork": true,
+  "rewritePackageManagers": true,
+  "outputCompaction": {
+    "enabled": true,
+    "stripAnsi": true,
+    "sourceCodeFilteringEnabled": true,
+    "sourceCodeFiltering": "minimal",
+    "aggregateTestOutput": true,
+    "filterBuildOutput": true,
+    "compactGitOutput": true,
+    "aggregateLinterOutput": true,
+    "groupSearchOutput": true,
+    "trackSavings": true,
+    "smartTruncate": {
+      "enabled": true,
+      "maxLines": 220
+    },
+    "truncate": {
+      "enabled": true,
+      "maxChars": 12000
+    }
+  }
+}
+```
+
+## Technical Details
 
-```text
-config/config.example.json
+### 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 tokenization and rewrite logic
+├── rewrite-rules.ts        # Rewrite rule catalog
+├── output-compactor.ts     # Tool result compaction pipeline
+├── output-metrics.ts       # Savings tracking and reporting
+├── 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
 ```
 
-Values are normalized/clamped on load and save to prevent invalid runtime state.
+### Event Hooks
+
+The extension hooks into Pi's event system:
+
+- **`beforeToolCall`** — Rewrites bash commands to rtk equivalents
+- **`afterToolResult`** — Compacts tool output before context consumption
+- **`command`** — Handles `/rtk` command and 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
 
 ```bash
+# Build (TypeScript compilation)
 npm run build
+
+# Lint
 npm run lint
+
+# Run tests
 npm run test
+
+# Full check (lint + test)
 npm run check
 ```
 
-## Project Layout
-
-- `index.ts` - root Pi auto-discovery entrypoint
-- `src/index.ts` - extension bootstrap/event wiring
-- `src/config-modal.ts` - `/rtk` settings modal + command handler
-- `src/config-store.ts` - config normalization/load/save
-- `src/command-rewriter.ts` - command tokenization and rewrite decisions
-- `src/rewrite-rules.ts` - rewrite rule catalog
-- `src/output-compactor.ts` - tool-result compaction pipeline
-- `src/output-metrics.ts` - savings tracking/reporting
-- `src/windows-command-helpers.ts` - Windows bash compatibility helpers
-- `src/techniques/*` - focused compaction techniques
-- `src/zellij-modal.ts` - bundled modal primitives used by settings UI
-- `config/config.example.json` - starter config template
-
 ## Credits
 
-This extension was built with inspiration from:
-
-- [`mcowger/pi-rtk`](https://github.com/mcowger/pi-rtk)
-- [`rtk-ai/rtk`](https://github.com/rtk-ai/rtk)
+Inspired by:
+- [mcowger/pi-rtk](https://github.com/mcowger/pi-rtk)
+- [rtk-ai/rtk](https://github.com/rtk-ai/rtk)
 
 ## License
 
-MIT
+[MIT](LICENSE) © MasuRii

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-rtk-optimizer",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Pi extension that optimizes RTK command rewriting and tool output compaction for the coding agent.",
   "type": "module",
   "main": "./index.ts",