pi-rtk-optimizer 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-03-02
+
+### Changed
+- Renamed extension/package from `rtk-integration` to `pi-rtk-optimizer` to better reflect its full purpose: RTK command rewrite plus tool-output compaction optimization.
+- Updated extension identity references across config path resolution, modal UI labeling, installation commands, package metadata, and build check artifact naming.
+
+## [0.2.0] - 2026-03-02
+
+### Changed
+- Reorganized extension into a publish-ready package layout:
+  - moved implementation modules into `src/`
+  - kept root `index.ts` as stable Pi auto-discovery entrypoint
+  - added `config/config.example.json` for distributable config starter
+- Vendored modal UI dependency as `src/zellij-modal.ts` so the package no longer depends on sibling extension paths.
+- Updated TypeScript project includes for the new modular layout.
+
+### Added
+- Public repository scaffolding:
+  - `README.md`
+  - `CHANGELOG.md`
+  - `LICENSE`
+  - `.gitignore`
+  - `.npmignore`
+- Distribution metadata in `package.json`:
+  - `description`, `keywords`, `files`, `engines`, `publishConfig`, repository links
+  - standard `build`, `lint`, `test`, and `check` scripts
+- Credits section referencing upstream inspiration projects:
+  - `mcowger/pi-rtk`
+  - `rtk-ai/rtk`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MasuRii
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# 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.
+
+![background](asset/pi-rtk-optimizer-background.png)
+
+## 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
+
+## Installation
+
+### Local extension folder
+
+Place this folder in:
+
+- Global: `~/.pi/agent/extensions/pi-rtk-optimizer`
+- Project: `.pi/extensions/pi-rtk-optimizer`
+
+Pi auto-discovers these paths.
+
+### As an npm package
+
+```bash
+pi install npm:pi-rtk-optimizer
+```
+
+Or from git:
+
+```bash
+pi install git:github.com/MasuRii/pi-rtk-optimizer
+```
+
+## Usage
+
+Open settings modal:
+
+```text
+/rtk
+```
+
+Subcommands:
+
+```text
+/rtk show
+/rtk path
+/rtk verify
+/rtk stats
+/rtk clear-stats
+/rtk reset
+/rtk help
+```
+
+## Configuration
+
+Runtime config is stored at:
+
+```text
+~/.pi/agent/extensions/pi-rtk-optimizer/config.json
+```
+
+A starter file is included as:
+
+```text
+config/config.example.json
+```
+
+Values are normalized/clamped on load and save to prevent invalid runtime state.
+
+## Development
+
+```bash
+npm run build
+npm run lint
+npm run 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)
+
+## License
+
+MIT

package/config/config.example.json

@@ -0,0 +1,35 @@
+{
+  "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,
+    "truncate": {
+      "enabled": true,
+      "maxChars": 12000
+    },
+    "sourceCodeFiltering": "minimal",
+    "smartTruncate": {
+      "enabled": true,
+      "maxLines": 220
+    },
+    "aggregateTestOutput": true,
+    "filterBuildOutput": true,
+    "compactGitOutput": true,
+    "aggregateLinterOutput": true,
+    "groupSearchOutput": true,
+    "trackSavings": true
+  }
+}

package/index.ts

@@ -0,0 +1,3 @@
+import rtkIntegrationExtension from "./src/index.js";
+
+export default rtkIntegrationExtension;

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "pi-rtk-optimizer",
+  "version": "0.3.0",
+  "description": "Pi extension that optimizes RTK command rewriting and tool output compaction for the coding agent.",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "config/config.example.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
+    "lint": "npm run build",
+    "test": "bun ./src/output-compactor-test.ts",
+    "check": "npm run lint && npm run test",
+    "build:check": "bunx esbuild ./index.ts --bundle --platform=node --format=esm --outfile=./.pi-rtk-optimizer-check.mjs --external:@mariozechner/pi-coding-agent --external:@mariozechner/pi-tui && bun -e \"import { unlinkSync } from 'node:fs'; unlinkSync('./.pi-rtk-optimizer-check.mjs');\""
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "rtk",
+    "token-optimization",
+    "tool-compaction",
+    "coding-agent"
+  ],
+  "author": "MasuRii",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MasuRii/pi-rtk-optimizer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MasuRii/pi-rtk-optimizer/issues"
+  },
+  "homepage": "https://github.com/MasuRii/pi-rtk-optimizer#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  }
+}

package/src/command-completions.ts

@@ -0,0 +1,49 @@
+import type { AutocompleteItem } from "@mariozechner/pi-tui";
+
+interface CompletionDefinition {
+	name: string;
+	description: string;
+}
+
+const TOP_LEVEL_SUBCOMMANDS: CompletionDefinition[] = [
+	{ name: "show", description: "Show current RTK config + runtime summary" },
+	{ name: "path", description: "Show RTK config file path" },
+	{ name: "verify", description: "Check whether rtk binary is available" },
+	{ name: "stats", description: "Show output compaction metrics" },
+	{ name: "clear-stats", description: "Clear output compaction metrics" },
+	{ name: "reset", description: "Reset RTK settings to defaults" },
+	{ name: "help", description: "Show usage help" },
+];
+
+function startsWithFilter(value: string, prefix: string): boolean {
+	if (!prefix) {
+		return true;
+	}
+	return value.startsWith(prefix);
+}
+
+function mapCompletions(values: CompletionDefinition[]): AutocompleteItem[] {
+	return values.map((entry) => ({
+		value: entry.name,
+		label: entry.name,
+		description: entry.description,
+	}));
+}
+
+export function getRtkArgumentCompletions(argumentPrefix: string): AutocompleteItem[] | null {
+	const normalized = argumentPrefix.trimStart().toLowerCase();
+	if (!normalized) {
+		return mapCompletions(TOP_LEVEL_SUBCOMMANDS);
+	}
+
+	if (normalized.includes(" ")) {
+		return null;
+	}
+
+	const filtered = TOP_LEVEL_SUBCOMMANDS.filter((entry) => startsWithFilter(entry.name, normalized));
+	if (filtered.length === 0) {
+		return null;
+	}
+
+	return mapCompletions(filtered);
+}

package/src/command-rewriter.ts

@@ -0,0 +1,349 @@
+import type { RtkIntegrationConfig } from "./types.js";
+import { RTK_REWRITE_RULES, type RtkRewriteCategory, type RtkRewriteRule } from "./rewrite-rules.js";
+
+const ENV_PREFIX_PATTERN = /^((?:[A-Za-z_][A-Za-z0-9_]*=[^\s]*\s+)*)/;
+
+type CommandToken =
+	| {
+			type: "segment";
+			value: string;
+	  }
+	| {
+			type: "separator";
+			value: string;
+	  };
+
+export interface RewriteDecision {
+	changed: boolean;
+	originalCommand: string;
+	rewrittenCommand: string;
+	rule?: RtkRewriteRule;
+	reason:
+		| "ok"
+		| "empty"
+		| "already_rtk"
+		| "heredoc"
+		| "disabled_category"
+		| "no_match";
+}
+
+interface SegmentRewriteResult {
+	value: string;
+	changed: boolean;
+	rule?: RtkRewriteRule;
+	skippedByDisabledCategory: boolean;
+	considered: boolean;
+	alreadyRtk: boolean;
+}
+
+interface SingleSegmentRewriteResult {
+	changed: boolean;
+	rule?: RtkRewriteRule;
+	rewrittenBody?: string;
+	skippedByDisabledCategory: boolean;
+	alreadyRtk: boolean;
+}
+
+function categoryEnabled(config: RtkIntegrationConfig, category: RtkRewriteCategory): boolean {
+	switch (category) {
+		case "gitGithub":
+			return config.rewriteGitGithub;
+		case "filesystem":
+			return config.rewriteFilesystem;
+		case "rust":
+			return config.rewriteRust;
+		case "javascript":
+			return config.rewriteJavaScript;
+		case "python":
+			return config.rewritePython;
+		case "go":
+			return config.rewriteGo;
+		case "containers":
+			return config.rewriteContainers;
+		case "network":
+			return config.rewriteNetwork;
+		case "packageManagers":
+			return config.rewritePackageManagers;
+		default:
+			return true;
+	}
+}
+
+function tokenizeCommand(command: string): CommandToken[] {
+	if (!command) {
+		return [];
+	}
+
+	const tokens: CommandToken[] = [];
+	let segmentStart = 0;
+	let quote: "'" | '"' | "`" | null = null;
+	let escaped = false;
+
+	for (let index = 0; index < command.length; index += 1) {
+		const char = command[index];
+
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+
+		if (quote !== null) {
+			if (char === "\\" && quote !== "'") {
+				escaped = true;
+				continue;
+			}
+			if (char === quote) {
+				quote = null;
+			}
+			continue;
+		}
+
+		if (char === "'" || char === '"' || char === "`") {
+			quote = char;
+			continue;
+		}
+
+		const nextChar = command[index + 1] ?? "";
+		if ((char === "&" && nextChar === "&") || (char === "|" && nextChar === "|")) {
+			const segment = command.slice(segmentStart, index);
+			if (segment.length > 0) {
+				tokens.push({ type: "segment", value: segment });
+			}
+			tokens.push({ type: "separator", value: command.slice(index, index + 2) });
+			segmentStart = index + 2;
+			index += 1;
+			continue;
+		}
+
+		if (char === ";") {
+			const segment = command.slice(segmentStart, index);
+			if (segment.length > 0) {
+				tokens.push({ type: "segment", value: segment });
+			}
+			tokens.push({ type: "separator", value: ";" });
+			segmentStart = index + 1;
+		}
+	}
+
+	const tail = command.slice(segmentStart);
+	if (tail.length > 0 || tokens.length === 0) {
+		tokens.push({ type: "segment", value: tail });
+	}
+
+	return tokens;
+}
+
+export function isAlreadyRtkCommand(command: string): boolean {
+	const trimmed = command.trimStart();
+	return /^rtk\s+/.test(trimmed) || /(?:^|\s)[^\s]*\/rtk\s+/.test(trimmed);
+}
+
+function applyPlatformProxyCommandFixups(command: string): string {
+	if (process.platform !== "win32") {
+		return command;
+	}
+
+	const windowsProxyExecutables: Array<[string, string]> = [
+		["npm", "npm.cmd"],
+		["npx", "npx.cmd"],
+		["pnpm", "pnpm.cmd"],
+		["yarn", "yarn.cmd"],
+	];
+
+	let next = command;
+	for (const [base, windowsExecutable] of windowsProxyExecutables) {
+		next = next.replace(
+			new RegExp(`^(rtk\\s+proxy\\s+)${base}(\\b)`, "i"),
+			`$1${windowsExecutable}$2`,
+		);
+	}
+
+	return next;
+}
+
+function rewriteSingleSegmentCommand(
+	segmentCommand: string,
+	config: RtkIntegrationConfig,
+): SingleSegmentRewriteResult {
+	const envMatch = segmentCommand.match(ENV_PREFIX_PATTERN);
+	const envPrefix = envMatch?.[1] ?? "";
+	const commandBody = segmentCommand.slice(envPrefix.length);
+
+	if (isAlreadyRtkCommand(segmentCommand) || isAlreadyRtkCommand(commandBody)) {
+		return {
+			changed: false,
+			alreadyRtk: true,
+			skippedByDisabledCategory: false,
+		};
+	}
+
+	let skippedByDisabledCategory = false;
+
+	for (const rule of RTK_REWRITE_RULES) {
+		if (!categoryEnabled(config, rule.category)) {
+			skippedByDisabledCategory = true;
+			continue;
+		}
+
+		rule.matcher.lastIndex = 0;
+		if (!rule.matcher.test(commandBody)) {
+			continue;
+		}
+
+		rule.matcher.lastIndex = 0;
+		const rewrittenBody = commandBody.replace(rule.matcher, rule.replacement);
+		const finalizedRewrittenBody = applyPlatformProxyCommandFixups(rewrittenBody);
+		if (finalizedRewrittenBody === commandBody) {
+			continue;
+		}
+
+		return {
+			changed: true,
+			rule,
+			rewrittenBody: finalizedRewrittenBody,
+			alreadyRtk: false,
+			skippedByDisabledCategory,
+		};
+	}
+
+	return {
+		changed: false,
+		alreadyRtk: false,
+		skippedByDisabledCategory,
+	};
+}
+
+function rewriteSegment(segment: string, config: RtkIntegrationConfig): SegmentRewriteResult {
+	const leadingWhitespace = segment.match(/^\s*/)?.[0] ?? "";
+	const trailingWhitespace = segment.match(/\s*$/)?.[0] ?? "";
+	const core = segment.trim();
+
+	if (!core) {
+		return {
+			value: segment,
+			changed: false,
+			skippedByDisabledCategory: false,
+			considered: false,
+			alreadyRtk: false,
+		};
+	}
+
+	const rewrite = rewriteSingleSegmentCommand(core, config);
+	if (!rewrite.changed || !rewrite.rule) {
+		return {
+			value: segment,
+			changed: false,
+			rule: undefined,
+			skippedByDisabledCategory: rewrite.skippedByDisabledCategory,
+			considered: true,
+			alreadyRtk: rewrite.alreadyRtk,
+		};
+	}
+
+	const envMatch = core.match(ENV_PREFIX_PATTERN);
+	const envPrefix = envMatch?.[1] ?? "";
+	const commandBody = core.slice(envPrefix.length);
+	rewrite.rule.matcher.lastIndex = 0;
+	const rewrittenBody = rewrite.rewrittenBody ?? commandBody.replace(rewrite.rule.matcher, rewrite.rule.replacement);
+
+	return {
+		value: `${leadingWhitespace}${envPrefix}${rewrittenBody}${trailingWhitespace}`,
+		changed: true,
+		rule: rewrite.rule,
+		skippedByDisabledCategory: rewrite.skippedByDisabledCategory,
+		considered: true,
+		alreadyRtk: false,
+	};
+}
+
+export function computeRewriteDecision(command: string, config: RtkIntegrationConfig): RewriteDecision {
+	const original = command;
+	const trimmed = command.trim();
+	if (!trimmed) {
+		return {
+			changed: false,
+			originalCommand: original,
+			rewrittenCommand: original,
+			reason: "empty",
+		};
+	}
+
+	if (trimmed.includes("<<")) {
+		return {
+			changed: false,
+			originalCommand: original,
+			rewrittenCommand: original,
+			reason: "heredoc",
+		};
+	}
+
+	const tokens = tokenizeCommand(command);
+	if (tokens.length === 0) {
+		return {
+			changed: false,
+			originalCommand: original,
+			rewrittenCommand: original,
+			reason: "no_match",
+		};
+	}
+
+	let changed = false;
+	let skippedByDisabledCategory = false;
+	let firstRule: RtkRewriteRule | undefined;
+	let consideredSegments = 0;
+	let alreadyRtkSegments = 0;
+
+	const rewrittenTokens = tokens.map((token) => {
+		if (token.type === "separator") {
+			return token;
+		}
+
+		const result = rewriteSegment(token.value, config);
+		if (result.considered) {
+			consideredSegments += 1;
+			if (result.alreadyRtk) {
+				alreadyRtkSegments += 1;
+			}
+		}
+		if (result.skippedByDisabledCategory) {
+			skippedByDisabledCategory = true;
+		}
+		if (result.changed) {
+			changed = true;
+			if (!firstRule) {
+				firstRule = result.rule;
+			}
+		}
+
+		return {
+			type: "segment" as const,
+			value: result.value,
+		};
+	});
+
+	if (changed) {
+		return {
+			changed: true,
+			originalCommand: original,
+			rewrittenCommand: rewrittenTokens.map((token) => token.value).join(""),
+			rule: firstRule,
+			reason: "ok",
+		};
+	}
+
+	if (consideredSegments > 0 && consideredSegments === alreadyRtkSegments) {
+		return {
+			changed: false,
+			originalCommand: original,
+			rewrittenCommand: original,
+			reason: "already_rtk",
+		};
+	}
+
+	return {
+		changed: false,
+		originalCommand: original,
+		rewrittenCommand: original,
+		reason: skippedByDisabledCategory ? "disabled_category" : "no_match",
+	};
+}