@heyhuynhgiabuu/pi-pretty 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 huynhgiabuu
+
+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,189 @@
+# pi-pretty
+
+A [pi](https://pi.dev) extension that enhances built-in tool output with **syntax highlighting**, **file-type icons**, **tree views**, and **colored status indicators** — all rendered directly in your terminal.
+
+> **Status:** Early release.
+
+> Companion to [@heyhuynhgiabuu/pi-diff](https://github.com/heyhuynhgiabuu/pi-diff) which handles `write`/`edit` diffs.
+
+## Features
+
+| Tool | Enhancement |
+|------|-------------|
+| **read** | Syntax-highlighted file content with line numbers (190+ languages via Shiki) |
+| **bash** | Colored exit status (`✓ exit 0` / `✗ exit 1`), line count |
+| **ls** | Tree-view directory listing with file-type icons (📁🟦🐍🦀…) |
+| **find** | Grouped results by directory with file-type icons |
+| **grep** | Highlighted pattern matches with file headers and line numbers |
+
+## Install
+
+```bash
+pi install npm:@heyhuynhgiabuu/pi-pretty
+```
+
+Or load directly for development:
+
+```bash
+pi -e ./src/index.ts
+```
+
+## How It Works
+
+pi-pretty wraps the built-in SDK tools (`createReadTool`, `createBashTool`, `createLsTool`, `createFindTool`, `createGrepTool`). For each tool:
+
+1. **Delegates** to the original `execute()` — no behavior changes
+2. **Attaches metadata** to `result.details` for custom rendering
+3. **Renders** enhanced output via `renderCall` / `renderResult`
+
+The agent sees the same tool results. Only the TUI display changes.
+
+## Configuration
+
+All settings via environment variables. Add to your shell profile or `.envrc`:
+
+### Theme
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PRETTY_THEME` | `github-dark` | Shiki theme for syntax highlighting |
+
+### Limits
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PRETTY_MAX_HL_CHARS` | `80000` | Skip syntax highlighting above this |
+| `PRETTY_MAX_PREVIEW_LINES` | `80` | Max lines shown in rendered output |
+| `PRETTY_CACHE_LIMIT` | `128` | LRU cache entries for highlighted blocks |
+
+### Example `.envrc`
+
+```bash
+export PRETTY_THEME="catppuccin-mocha"
+export PRETTY_MAX_PREVIEW_LINES=120
+```
+
+## Tool Details
+
+### `read` — Syntax Highlighting
+
+When the agent reads a file, pi-pretty renders it with:
+- Shiki syntax highlighting (190+ languages, auto-detected from extension)
+- Line numbers in a left gutter
+- Long lines truncated with `›` indicator
+- Respects `offset` and `limit` parameters
+
+### `bash` — Exit Status
+
+Bash command results show:
+- `✓ exit 0` in green for success
+- `✗ exit 1` in red for failure
+- `⚡ killed` in yellow for terminated processes
+- Line count for multi-line output
+
+### `ls` — Tree View
+
+Directory listings rendered as:
+```
+  3 entries
+  ├── 📁 src
+  ├── 📦 package.json
+  └── 📖 README.md
+```
+
+File-type icons auto-detected from extension and filename.
+
+### `find` — Grouped Results
+
+Find results grouped by directory:
+```
+  5 files
+  📁 src/
+    ├── 🟦 index.ts
+    └── 🟦 utils.ts
+  📁 test/
+    ├── 🟦 index.test.ts
+    └── 🟦 utils.test.ts
+```
+
+### `grep` — Highlighted Matches
+
+Grep results with file headers and matched text highlighted:
+```
+  3 matches
+  🟦 src/index.ts
+    12 │ const result = await createReadTool(cwd);
+    45 │ export function createReadTool(path: string) {
+
+  🟦 src/utils.ts
+    8  │ import { createReadTool } from "./index";
+```
+
+## File-Type Icons
+
+| Icon | Extensions |
+|------|-----------|
+| 🟦 | `.ts`, `.tsx`, `tsconfig.json` |
+| 🟨 | `.js`, `.jsx`, `.mjs`, `.cjs` |
+| 🐍 | `.py`, `pyproject.toml` |
+| 🦀 | `.rs`, `Cargo.toml` |
+| 🔵 | `.go`, `go.mod` |
+| ☕ | `.java` |
+| 🍊 | `.swift` |
+| 💎 | `.rb` |
+| 🌐 | `.html` |
+| 🎨 | `.css`, `.scss`, `.less` |
+| 📋 | `.json`, `.yaml`, `.toml` |
+| 📝 | `.md`, `.mdx` |
+| 🐚 | `.sh`, `.bash`, `.zsh` |
+| 🖼️ | `.png`, `.jpg`, `.svg`, `.webp` |
+| 📦 | `package.json` |
+| 🐳 | `Dockerfile` |
+| 🔐 | `.env`, `.envrc` |
+| 📖 | `README.md` |
+| ⚖️ | `LICENSE` |
+
+## Architecture
+
+```
+src/
+└── index.ts    # Extension entry — wraps read/bash/ls/find/grep with pretty rendering
+```
+
+### Key internals
+
+| Component | Purpose |
+|-----------|---------|
+| `hlBlock()` | Shiki ANSI highlighting with LRU cache |
+| `renderFileContent()` | Line-numbered syntax-highlighted file display |
+| `renderBashOutput()` | Colored exit status + stderr detection |
+| `renderTree()` | Tree-view with connectors and file icons |
+| `renderFindResults()` | Directory-grouped file list with icons |
+| `renderGrepResults()` | Pattern-highlighted matches with file headers |
+| `fileIcon()` | Extension → emoji icon mapper |
+| `lang()` | Extension → Shiki language mapper |
+
+## Development
+
+```bash
+git clone https://github.com/heyhuynhgiabuu/pi-pretty.git
+cd pi-pretty
+npm install
+npm run typecheck
+npm run lint
+npm test
+```
+
+### Load in pi for testing
+
+```bash
+pi -e ./src/index.ts
+```
+
+## Related
+
+- [@heyhuynhgiabuu/pi-diff](https://github.com/heyhuynhgiabuu/pi-diff) — Syntax-highlighted diffs for `write`/`edit` tools
+
+## License
+
+MIT — [huynhgiabuu](https://github.com/heyhuynhgiabuu)

package/biome.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "tab",
+    "lineWidth": 120
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@heyhuynhgiabuu/pi-pretty",
+  "version": "0.1.0",
+  "description": "Pretty terminal output for pi — syntax-highlighted file reads, colored bash output, tree-view directory listings, and more.",
+  "author": "huynhgiabuu",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/heyhuynhgiabuu/pi-pretty.git"
+  },
+  "homepage": "https://github.com/heyhuynhgiabuu/pi-pretty#readme",
+  "bugs": {
+    "url": "https://github.com/heyhuynhgiabuu/pi-pretty/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "syntax-highlighting",
+    "shiki",
+    "terminal",
+    "pretty-print"
+  ],
+  "dependencies": {
+    "@shikijs/cli": "^4.0.2"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "@biomejs/biome": "^2.3.5",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --fix src/",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

package/src/index.ts

@@ -0,0 +1,890 @@
+/**
+ * pi-pretty — Pretty terminal output for pi built-in tools.
+ *
+ * @module pi-pretty
+ * @see https://github.com/heyhuynhgiabuu/pi-pretty
+ *
+ * Enhances:
+ *   • read  — syntax-highlighted file content with line numbers
+ *   • bash  — colored exit status, stderr highlighting
+ *   • ls    — tree-view directory listing with file-type icons
+ *   • find  — grouped results with file-type icons
+ *   • grep  — syntax-highlighted match context with line numbers
+ *
+ * Architecture:
+ *   1. Wrap SDK factory tools (createReadTool, createBashTool, etc.)
+ *   2. Delegate to original execute() — no behavior changes
+ *   3. Attach metadata in result.details for custom renderCall/renderResult
+ *   4. Async Shiki highlighting with ctx.invalidate() for non-blocking renders
+ *
+ * Performance:
+ *   • Shared Shiki singleton (managed by @shikijs/cli)
+ *   • LRU cache for highlighted blocks
+ *   • Large-file fallback (skip highlighting, still show line numbers)
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { basename, dirname, extname, relative } from "node:path";
+
+import { codeToANSI } from "@shikijs/cli";
+import type { BundledLanguage, BundledTheme } from "shiki";
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const THEME: BundledTheme =
+	(process.env.PRETTY_THEME as BundledTheme | undefined) ?? "github-dark";
+
+function envInt(name: string, fallback: number): number {
+	const v = Number.parseInt(process.env[name] ?? "", 10);
+	return Number.isFinite(v) && v > 0 ? v : fallback;
+}
+
+const MAX_HL_CHARS = envInt("PRETTY_MAX_HL_CHARS", 80_000);
+const MAX_PREVIEW_LINES = envInt("PRETTY_MAX_PREVIEW_LINES", 80);
+const CACHE_LIMIT = envInt("PRETTY_CACHE_LIMIT", 128);
+
+// ---------------------------------------------------------------------------
+// ANSI
+// ---------------------------------------------------------------------------
+
+const RST = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const ITALIC = "\x1b[3m";
+
+const FG_LNUM = "\x1b[38;2;100;100;100m";
+const FG_DIM = "\x1b[38;2;80;80;80m";
+const FG_RULE = "\x1b[38;2;50;50;50m";
+const FG_GREEN = "\x1b[38;2;100;180;120m";
+const FG_RED = "\x1b[38;2;200;100;100m";
+const FG_YELLOW = "\x1b[38;2;220;180;80m";
+const FG_BLUE = "\x1b[38;2;100;140;220m";
+const FG_CYAN = "\x1b[38;2;80;190;190m";
+const FG_MUTED = "\x1b[38;2;139;148;158m";
+const FG_ORANGE = "\x1b[38;2;220;140;60m";
+const FG_PURPLE = "\x1b[38;2;170;120;200m";
+
+const BG_STDERR = "\x1b[48;2;40;25;25m";
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+// ---------------------------------------------------------------------------
+// Low-contrast fix (same as pi-diff)
+// ---------------------------------------------------------------------------
+
+function isLowContrastShikiFg(params: string): boolean {
+	if (params === "30" || params === "90") return true;
+	if (params === "38;5;0" || params === "38;5;8") return true;
+	if (!params.startsWith("38;2;")) return false;
+	const parts = params.split(";").map(Number);
+	if (parts.length !== 5 || parts.some((n) => !Number.isFinite(n)))
+		return false;
+	const [, , r, g, b] = parts;
+	const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+	return luminance < 72;
+}
+
+function normalizeShikiContrast(ansi: string): string {
+	return ansi.replace(
+		/\x1b\[([0-9;]*)m/g,
+		(seq, params: string) =>
+			isLowContrastShikiFg(params) ? FG_MUTED : seq,
+	);
+}
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+function strip(s: string): string {
+	return s.replace(ANSI_RE, "");
+}
+
+function termW(): number {
+	const raw =
+		process.stdout.columns ||
+		(process.stderr as any).columns ||
+		Number.parseInt(process.env.COLUMNS ?? "", 10) ||
+		200;
+	return Math.max(80, Math.min(raw - 4, 210));
+}
+
+function shortPath(cwd: string, home: string, p: string): string {
+	if (!p) return "";
+	const r = relative(cwd, p);
+	if (!r.startsWith("..") && !r.startsWith("/")) return r;
+	return p.replace(home, "~");
+}
+
+function rule(w: number): string {
+	return `${FG_RULE}${"─".repeat(w)}${RST}`;
+}
+
+function lnum(n: number, w: number): string {
+	const v = String(n);
+	return `${FG_LNUM}${" ".repeat(Math.max(0, w - v.length))}${v}${RST}`;
+}
+
+// ---------------------------------------------------------------------------
+// Language detection
+// ---------------------------------------------------------------------------
+
+const EXT_LANG: Record<string, BundledLanguage> = {
+	ts: "typescript", tsx: "tsx", js: "javascript", jsx: "jsx",
+	mjs: "javascript", cjs: "javascript",
+	py: "python", rb: "ruby", rs: "rust", go: "go", java: "java",
+	c: "c", cpp: "cpp", h: "c", hpp: "cpp", cs: "csharp",
+	swift: "swift", kt: "kotlin",
+	html: "html", css: "css", scss: "scss", less: "css",
+	json: "json", jsonc: "jsonc", yaml: "yaml", yml: "yaml", toml: "toml",
+	md: "markdown", mdx: "mdx", sql: "sql", sh: "bash", bash: "bash", zsh: "bash",
+	lua: "lua", php: "php", dart: "dart", xml: "xml",
+	graphql: "graphql", svelte: "svelte", vue: "vue",
+	dockerfile: "dockerfile", makefile: "make",
+	zig: "zig", nim: "nim", elixir: "elixir", ex: "elixir",
+	erb: "erb", hbs: "handlebars",
+};
+
+function lang(fp: string): BundledLanguage | undefined {
+	const base = basename(fp).toLowerCase();
+	if (base === "dockerfile") return "dockerfile";
+	if (base === "makefile" || base === "gnumakefile") return "make";
+	if (base === ".envrc" || base === ".env") return "bash";
+	return EXT_LANG[extname(fp).slice(1).toLowerCase()];
+}
+
+// ---------------------------------------------------------------------------
+// File-type icons
+// ---------------------------------------------------------------------------
+
+const ICON_DIR = "📁";
+const ICON_DEFAULT = "  ";
+
+const EXT_ICON: Record<string, string> = {
+	ts: "🟦", tsx: "🟦", js: "🟨", jsx: "🟨", mjs: "🟨", cjs: "🟨",
+	py: "🐍", rb: "💎", rs: "🦀", go: "🔵", java: "☕",
+	c: "🔧", cpp: "🔧", h: "🔧", hpp: "🔧", cs: "🟪",
+	swift: "🍊", kt: "🟣",
+	html: "🌐", css: "🎨", scss: "🎨", less: "🎨",
+	json: "📋", yaml: "📋", yml: "📋", toml: "📋",
+	md: "📝", mdx: "📝",
+	sql: "🗃️", sh: "🐚", bash: "🐚", zsh: "🐚",
+	png: "🖼️", jpg: "🖼️", jpeg: "🖼️", gif: "🖼️", svg: "🖼️", webp: "🖼️",
+	lock: "🔒", env: "🔐",
+};
+
+const NAME_ICON: Record<string, string> = {
+	"package.json": "📦", "package-lock.json": "📦",
+	"tsconfig.json": "🟦", "biome.json": "🧹",
+	".gitignore": "🙈", ".env": "🔐", ".envrc": "🔐",
+	dockerfile: "🐳", makefile: "🔧", gnumakefile: "🔧",
+	"readme.md": "📖", "license": "⚖️",
+	"cargo.toml": "🦀", "go.mod": "🔵", "pyproject.toml": "🐍",
+};
+
+function fileIcon(fp: string): string {
+	const base = basename(fp).toLowerCase();
+	if (NAME_ICON[base]) return NAME_ICON[base];
+	const ext = extname(fp).slice(1).toLowerCase();
+	return EXT_ICON[ext] ?? ICON_DEFAULT;
+}
+
+// ---------------------------------------------------------------------------
+// Shiki ANSI cache
+// ---------------------------------------------------------------------------
+
+// Pre-warm
+codeToANSI("", "typescript", THEME).catch(() => {});
+
+const _cache = new Map<string, string[]>();
+
+function _touch(k: string, v: string[]): string[] {
+	_cache.delete(k);
+	_cache.set(k, v);
+	while (_cache.size > CACHE_LIMIT) {
+		const first = _cache.keys().next().value;
+		if (first === undefined) break;
+		_cache.delete(first);
+	}
+	return v;
+}
+
+async function hlBlock(
+	code: string,
+	language: BundledLanguage | undefined,
+): Promise<string[]> {
+	if (!code) return [""];
+	if (!language || code.length > MAX_HL_CHARS) return code.split("\n");
+
+	const k = `${THEME}\0${language}\0${code}`;
+	const hit = _cache.get(k);
+	if (hit) return _touch(k, hit);
+
+	try {
+		const ansi = normalizeShikiContrast(await codeToANSI(code, language, THEME));
+		const out = (ansi.endsWith("\n") ? ansi.slice(0, -1) : ansi).split("\n");
+		return _touch(k, out);
+	} catch {
+		return code.split("\n");
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Renderers
+// ---------------------------------------------------------------------------
+
+/** Render syntax-highlighted file content with line numbers. */
+async function renderFileContent(
+	content: string,
+	filePath: string,
+	offset = 1,
+	maxLines = MAX_PREVIEW_LINES,
+): Promise<string> {
+	const lines = content.split("\n");
+	const total = lines.length;
+	const show = lines.slice(0, maxLines);
+	const lg = lang(filePath);
+	const hl = await hlBlock(show.join("\n"), lg);
+
+	const tw = termW();
+	const startLine = offset;
+	const endLine = startLine + show.length - 1;
+	const nw = Math.max(3, String(endLine).length);
+	const gw = nw + 3; // num + " │ "
+	const cw = Math.max(20, tw - gw);
+
+	const out: string[] = [];
+	out.push(rule(tw));
+
+	for (let i = 0; i < hl.length; i++) {
+		const ln = startLine + i;
+		const code = hl[i] ?? show[i] ?? "";
+		const plain = strip(code);
+		// Truncate if wider than available
+		let display = code;
+		if (plain.length > cw) {
+			let vis = 0;
+			let j = 0;
+			while (j < code.length && vis < cw - 1) {
+				if (code[j] === "\x1b") {
+					const e = code.indexOf("m", j);
+					if (e !== -1) {
+						j = e + 1;
+						continue;
+					}
+				}
+				vis++;
+				j++;
+			}
+			display = code.slice(0, j) + RST + FG_DIM + "›" + RST;
+		}
+		out.push(`${lnum(ln, nw)} ${FG_RULE}│${RST} ${display}${RST}`);
+	}
+
+	out.push(rule(tw));
+	if (total > maxLines) {
+		out.push(
+			`${FG_DIM}  … ${total - maxLines} more lines (${total} total)${RST}`,
+		);
+	}
+	return out.join("\n");
+}
+
+/** Render bash output with colored exit code and stderr highlighting. */
+function renderBashOutput(
+	text: string,
+	exitCode: number | null,
+): { summary: string; body: string } {
+	const isOk = exitCode === 0;
+	const statusFg = isOk ? FG_GREEN : FG_RED;
+	const statusIcon = isOk ? "✓" : "✗";
+	const codeStr =
+		exitCode !== null
+			? `${statusFg}${statusIcon} exit ${exitCode}${RST}`
+			: `${FG_YELLOW}⚡ killed${RST}`;
+
+	const lines = text.split("\n");
+	const maxShow = MAX_PREVIEW_LINES;
+	const show = lines.slice(0, maxShow);
+	const remaining = lines.length - maxShow;
+
+	let body = show.join("\n");
+	if (remaining > 0) {
+		body += `\n${FG_DIM}  … ${remaining} more lines${RST}`;
+	}
+
+	return { summary: codeStr, body };
+}
+
+/** Render ls output as a tree view with icons. */
+function renderTree(text: string, basePath: string): string {
+	const lines = text.trim().split("\n").filter(Boolean);
+	if (!lines.length) return `${FG_DIM}(empty directory)${RST}`;
+
+	const out: string[] = [];
+	const total = lines.length;
+	const show = lines.slice(0, MAX_PREVIEW_LINES);
+
+	for (let i = 0; i < show.length; i++) {
+		const entry = show[i].trim();
+		const isLast = i === show.length - 1 && total <= MAX_PREVIEW_LINES;
+		const prefix = isLast ? "└── " : "├── ";
+		const connector = `${FG_RULE}${prefix}${RST}`;
+
+		// Detect directories (entries ending with /)
+		const isDir = entry.endsWith("/");
+		const name = isDir ? entry.slice(0, -1) : entry;
+		const icon = isDir ? ICON_DIR : fileIcon(name);
+		const fg = isDir ? FG_BLUE + BOLD : "";
+		const reset = isDir ? RST : "";
+
+		out.push(`${connector}${icon} ${fg}${name}${reset}`);
+	}
+
+	if (total > MAX_PREVIEW_LINES) {
+		out.push(
+			`${FG_RULE}└── ${RST}${FG_DIM}… ${total - MAX_PREVIEW_LINES} more entries${RST}`,
+		);
+	}
+
+	return out.join("\n");
+}
+
+/** Render find results grouped by directory with icons. */
+function renderFindResults(text: string): string {
+	const lines = text.trim().split("\n").filter(Boolean);
+	if (!lines.length) return `${FG_DIM}(no matches)${RST}`;
+
+	// Group by directory
+	const groups = new Map<string, string[]>();
+	for (const line of lines) {
+		const trimmed = line.trim();
+		const dir = dirname(trimmed) || ".";
+		const file = basename(trimmed);
+		if (!groups.has(dir)) groups.set(dir, []);
+		groups.get(dir)!.push(file);
+	}
+
+	const out: string[] = [];
+	let count = 0;
+
+	for (const [dir, files] of groups) {
+		if (count > 0) out.push(""); // blank line between groups
+		out.push(`${ICON_DIR} ${FG_BLUE}${BOLD}${dir}/${RST}`);
+		for (let i = 0; i < files.length; i++) {
+			if (count >= MAX_PREVIEW_LINES) {
+				out.push(
+					`  ${FG_DIM}… ${lines.length - count} more files${RST}`,
+				);
+				return out.join("\n");
+			}
+			const isLast = i === files.length - 1;
+			const prefix = isLast ? "└── " : "├── ";
+			const icon = fileIcon(files[i]);
+			out.push(`  ${FG_RULE}${prefix}${RST}${icon} ${files[i]}`);
+			count++;
+		}
+	}
+
+	return out.join("\n");
+}
+
+/** Render grep results with highlighted matches and line numbers. */
+async function renderGrepResults(
+	text: string,
+	pattern: string,
+): Promise<string> {
+	const lines = text.split("\n");
+	if (!lines.length || (lines.length === 1 && !lines[0].trim()))
+		return `${FG_DIM}(no matches)${RST}`;
+
+	const tw = termW();
+	const out: string[] = [];
+	let currentFile = "";
+	let count = 0;
+
+	// Try to build a regex for highlighting
+	let re: RegExp | null = null;
+	try {
+		re = new RegExp(`(${pattern})`, "gi");
+	} catch {
+		// invalid regex — skip highlighting
+	}
+
+	for (const line of lines) {
+		if (count >= MAX_PREVIEW_LINES) {
+			out.push(`${FG_DIM}  … more matches${RST}`);
+			break;
+		}
+
+		// ripgrep-style: "file:line:content" or "file-line-content" or just "file"
+		const fileMatch = line.match(/^(.+?)[:\-](\d+)[:\-](.*)$/);
+		if (fileMatch) {
+			const [, file, lineNo, content] = fileMatch;
+			if (file !== currentFile) {
+				if (currentFile) out.push(""); // blank line between files
+				const icon = fileIcon(file);
+				out.push(`${icon} ${FG_BLUE}${BOLD}${file}${RST}`);
+				currentFile = file;
+			}
+
+			const nw = Math.max(3, lineNo.length);
+			let display = content;
+			if (re) {
+				display = content.replace(
+					re,
+					`${RST}${FG_YELLOW}${BOLD}$1${RST}`,
+				);
+			}
+			out.push(`  ${lnum(Number(lineNo), nw)} ${FG_RULE}│${RST} ${display}${RST}`);
+			count++;
+		} else if (line.trim() === "--") {
+			// ripgrep separator
+			out.push(`  ${FG_DIM}  ···${RST}`);
+		} else if (line.trim()) {
+			out.push(line);
+			count++;
+		}
+	}
+
+	return out.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Extension entry point
+// ---------------------------------------------------------------------------
+
+export default function piPrettyExtension(pi: any): void {
+	let createReadTool: any;
+	let createBashTool: any;
+	let createLsTool: any;
+	let createFindTool: any;
+	let createGrepTool: any;
+	let TextComponent: any;
+
+	try {
+		const sdk = require("@mariozechner/pi-coding-agent");
+		createReadTool = sdk.createReadTool;
+		createBashTool = sdk.createBashTool;
+		createLsTool = sdk.createLsTool;
+		createFindTool = sdk.createFindTool;
+		createGrepTool = sdk.createGrepTool;
+		TextComponent = require("@mariozechner/pi-tui").Text;
+	} catch {
+		return;
+	}
+	if (!createReadTool || !TextComponent) return;
+
+	const cwd = process.cwd();
+	const home = process.env.HOME ?? "";
+	const sp = (p: string) => shortPath(cwd, home, p);
+
+	// ===================================================================
+	// read — syntax-highlighted file content
+	// ===================================================================
+
+	const origRead = createReadTool(cwd);
+
+	pi.registerTool({
+		...origRead,
+		name: "read",
+
+		async execute(tid: string, params: any, sig: any, upd: any, ctx: any) {
+			const result = await origRead.execute(tid, params, sig, upd, ctx);
+
+			const fp = params.path ?? "";
+			const offset = params.offset ?? 1;
+
+			// Extract text content for rendering
+			const textContent = result.content
+				?.filter((c: any) => c.type === "text")
+				.map((c: any) => c.text || "")
+				.join("\n");
+
+			if (textContent && fp) {
+				const lineCount = textContent.split("\n").length;
+				(result as any).details = {
+					_type: "readFile",
+					filePath: fp,
+					content: textContent,
+					offset,
+					lineCount,
+				};
+			}
+
+			return result;
+		},
+
+		renderCall(args: any, theme: any, ctx: any) {
+			const fp = args?.path ?? "";
+			const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
+			const offset = args?.offset ? ` ${theme.fg("muted", `from line ${args.offset}`)}` : "";
+			const limit = args?.limit ? ` ${theme.fg("muted", `(${args.limit} lines)`)}` : "";
+			text.setText(
+				`${theme.fg("toolTitle", theme.bold("read"))} ${theme.fg("accent", sp(fp))}${offset}${limit}`,
+			);
+			return text;
+		},
+
+		renderResult(result: any, _opt: any, theme: any, ctx: any) {
+			const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
+
+			if (ctx.isError) {
+				const e = result.content
+					?.filter((c: any) => c.type === "text")
+					.map((c: any) => c.text || "")
+					.join("\n") ?? "Error";
+				text.setText(`\n${theme.fg("error", e)}`);
+				return text;
+			}
+
+			const d = result.details;
+			if (d?._type === "readFile" && d.content) {
+				const key = `read:${d.filePath}:${d.offset}:${d.lineCount}:${termW()}`;
+				if (ctx.state._rk !== key) {
+					ctx.state._rk = key;
+					const info = `${FG_DIM}${d.lineCount} lines${RST}`;
+					ctx.state._rt = `  ${info}`;
+
+					const maxShow = ctx.expanded ? d.lineCount : MAX_PREVIEW_LINES;
+					renderFileContent(d.content, d.filePath, d.offset, maxShow)
+						.then((rendered: string) => {
+							if (ctx.state._rk !== key) return;
+							ctx.state._rt = `  ${info}\n${rendered}`;
+							ctx.invalidate();
+						})
+						.catch(() => {});
+				}
+				text.setText(ctx.state._rt ?? `  ${FG_DIM}${d.lineCount} lines${RST}`);
+				return text;
+			}
+
+			// Fallback
+			const fallback = result.content?.[0]?.text ?? "read";
+			text.setText(`  ${theme.fg("dim", String(fallback).slice(0, 120))}`);
+			return text;
+		},
+	});
+
+	// ===================================================================
+	// bash — colored exit status
+	// ===================================================================
+
+	if (createBashTool) {
+		const origBash = createBashTool(cwd);
+
+		pi.registerTool({
+			...origBash,
+			name: "bash",
+
+			async execute(tid: string, params: any, sig: any, upd: any, ctx: any) {
+				const result = await origBash.execute(tid, params, sig, upd, ctx);
+
+				const textContent = result.content
+					?.filter((c: any) => c.type === "text")
+					.map((c: any) => c.text || "")
+					.join("\n");
+
+				// Try to extract exit code from the output
+				let exitCode: number | null = 0;
+				if (textContent) {
+					const exitMatch = textContent.match(
+						/(?:exit code|exited with|exit status)[:\s]*(\d+)/i,
+					);
+					if (exitMatch) exitCode = Number(exitMatch[1]);
+					// Check for common error indicators
+					if (
+						textContent.includes("command not found") ||
+						textContent.includes("No such file")
+					) {
+						exitCode = 1;
+					}
+				}
+
+				(result as any).details = {
+					_type: "bashResult",
+					text: textContent ?? "",
+					exitCode,
+					command: params.command ?? "",
+				};
+
+				return result;
+			},
+
+			renderCall(args: any, theme: any, ctx: any) {
+				const cmd = args?.command ?? "";
+				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
+				const timeout = args?.timeout
+					? ` ${theme.fg("muted", `(${args.timeout}s timeout)`)}`
+					: "";
+				text.setText(
+					`${theme.fg("toolTitle", theme.bold("bash"))} ${theme.fg("accent", cmd.length > 80 ? cmd.slice(0, 77) + "…" : cmd)}${timeout}`,
+				);
+				return text;
+			},
+
+			renderResult(result: any, _opt: any, theme: any, ctx: any) {
+				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
+
+				if (ctx.isError) {
+					const e = result.content
+						?.filter((c: any) => c.type === "text")
+						.map((c: any) => c.text || "")
+						.join("\n") ?? "Error";
+					text.setText(`\n${theme.fg("error", e)}`);
+					return text;
+				}
+
+				const d = result.details;
+				if (d?._type === "bashResult") {
+					const { summary } = renderBashOutput(d.text, d.exitCode);
+					const lines = d.text.split("\n").length;
+					const lineInfo = lines > 1 ? `  ${FG_DIM}(${lines} lines)${RST}` : "";
+					text.setText(`  ${summary}${lineInfo}`);
+					return text;
+				}
+
+				const fallback = result.content?.[0]?.text ?? "done";
+				text.setText(
+					`  ${theme.fg("dim", String(fallback).slice(0, 120))}`,
+				);
+				return text;
+			},
+		});
+	}
+
+	// ===================================================================
+	// ls — tree view with icons
+	// ===================================================================
+
+	if (createLsTool) {
+		const origLs = createLsTool(cwd);
+
+		pi.registerTool({
+			...origLs,
+			name: "ls",
+
+			async execute(tid: string, params: any, sig: any, upd: any, ctx: any) {
+				const result = await origLs.execute(tid, params, sig, upd, ctx);
+
+				const textContent = result.content
+					?.filter((c: any) => c.type === "text")
+					.map((c: any) => c.text || "")
+					.join("\n");
+
+				const fp = params.path ?? cwd;
+				const entryCount = textContent
+					? textContent.trim().split("\n").filter(Boolean).length
+					: 0;
+
+				(result as any).details = {
+					_type: "lsResult",
+					text: textContent ?? "",
+					path: fp,
+					entryCount,
+				};
+
+				return result;
+			},
+
+			renderCall(args: any, theme: any, ctx: any) {
+				const fp = args?.path ?? ".";
+				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
+				text.setText(
+					`${theme.fg("toolTitle", theme.bold("ls"))} ${theme.fg("accent", sp(fp))}`,
+				);
+				return text;
+			},
+
+			renderResult(result: any, _opt: any, theme: any, ctx: any) {
+				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
+
+				if (ctx.isError) {
+					const e = result.content
+						?.filter((c: any) => c.type === "text")
+						.map((c: any) => c.text || "")
+						.join("\n") ?? "Error";
+					text.setText(`\n${theme.fg("error", e)}`);
+					return text;
+				}
+
+				const d = result.details;
+				if (d?._type === "lsResult" && d.text) {
+					const tree = renderTree(d.text, d.path);
+					const info = `${FG_DIM}${d.entryCount} entries${RST}`;
+					text.setText(`  ${info}\n${tree}`);
+					return text;
+				}
+
+				const fallback = result.content?.[0]?.text ?? "listed";
+				text.setText(
+					`  ${theme.fg("dim", String(fallback).slice(0, 120))}`,
+				);
+				return text;
+			},
+		});
+	}
+
+	// ===================================================================
+	// find — grouped file list with icons
+	// ===================================================================
+
+	if (createFindTool) {
+		const origFind = createFindTool(cwd);
+
+		pi.registerTool({
+			...origFind,
+			name: "find",
+
+			async execute(tid: string, params: any, sig: any, upd: any, ctx: any) {
+				const result = await origFind.execute(tid, params, sig, upd, ctx);
+
+				const textContent = result.content
+					?.filter((c: any) => c.type === "text")
+					.map((c: any) => c.text || "")
+					.join("\n");
+
+				const matchCount = textContent
+					? textContent.trim().split("\n").filter(Boolean).length
+					: 0;
+
+				(result as any).details = {
+					_type: "findResult",
+					text: textContent ?? "",
+					pattern: params.pattern ?? "",
+					matchCount,
+				};
+
+				return result;
+			},
+
+			renderCall(args: any, theme: any, ctx: any) {
+				const pattern = args?.pattern ?? "";
+				const path = args?.path ? ` ${theme.fg("muted", `in ${sp(args.path)}`)}` : "";
+				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
+				text.setText(
+					`${theme.fg("toolTitle", theme.bold("find"))} ${theme.fg("accent", pattern)}${path}`,
+				);
+				return text;
+			},
+
+			renderResult(result: any, _opt: any, theme: any, ctx: any) {
+				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
+
+				if (ctx.isError) {
+					const e = result.content
+						?.filter((c: any) => c.type === "text")
+						.map((c: any) => c.text || "")
+						.join("\n") ?? "Error";
+					text.setText(`\n${theme.fg("error", e)}`);
+					return text;
+				}
+
+				const d = result.details;
+				if (d?._type === "findResult" && d.text) {
+					const rendered = renderFindResults(d.text);
+					const info = `${FG_DIM}${d.matchCount} files${RST}`;
+					text.setText(`  ${info}\n${rendered}`);
+					return text;
+				}
+
+				const fallback = result.content?.[0]?.text ?? "found";
+				text.setText(
+					`  ${theme.fg("dim", String(fallback).slice(0, 120))}`,
+				);
+				return text;
+			},
+		});
+	}
+
+	// ===================================================================
+	// grep — highlighted matches with line numbers
+	// ===================================================================
+
+	if (createGrepTool) {
+		const origGrep = createGrepTool(cwd);
+
+		pi.registerTool({
+			...origGrep,
+			name: "grep",
+
+			async execute(tid: string, params: any, sig: any, upd: any, ctx: any) {
+				const result = await origGrep.execute(tid, params, sig, upd, ctx);
+
+				const textContent = result.content
+					?.filter((c: any) => c.type === "text")
+					.map((c: any) => c.text || "")
+					.join("\n");
+
+				const matchCount = textContent
+					? textContent
+							.trim()
+							.split("\n")
+							.filter((l: string) => l.match(/^.+?[:\-]\d+[:\-]/))
+							.length
+					: 0;
+
+				(result as any).details = {
+					_type: "grepResult",
+					text: textContent ?? "",
+					pattern: params.pattern ?? "",
+					matchCount,
+				};
+
+				return result;
+			},
+
+			renderCall(args: any, theme: any, ctx: any) {
+				const pattern = args?.pattern ?? "";
+				const path = args?.path ? ` ${theme.fg("muted", `in ${sp(args.path)}`)}` : "";
+				const glob = args?.glob ? ` ${theme.fg("muted", `(${args.glob})`)}` : "";
+				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
+				text.setText(
+					`${theme.fg("toolTitle", theme.bold("grep"))} ${theme.fg("accent", pattern)}${path}${glob}`,
+				);
+				return text;
+			},
+
+			renderResult(result: any, _opt: any, theme: any, ctx: any) {
+				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
+
+				if (ctx.isError) {
+					const e = result.content
+						?.filter((c: any) => c.type === "text")
+						.map((c: any) => c.text || "")
+						.join("\n") ?? "Error";
+					text.setText(`\n${theme.fg("error", e)}`);
+					return text;
+				}
+
+				const d = result.details;
+				if (d?._type === "grepResult" && d.text) {
+					const key = `grep:${d.pattern}:${d.matchCount}:${termW()}`;
+					if (ctx.state._gk !== key) {
+						ctx.state._gk = key;
+						const info = `${FG_DIM}${d.matchCount} matches${RST}`;
+						ctx.state._gt = `  ${info}`;
+
+						renderGrepResults(d.text, d.pattern)
+							.then((rendered: string) => {
+								if (ctx.state._gk !== key) return;
+								ctx.state._gt = `  ${info}\n${rendered}`;
+								ctx.invalidate();
+							})
+							.catch(() => {});
+					}
+					text.setText(ctx.state._gt ?? `  ${FG_DIM}${d.matchCount} matches${RST}`);
+					return text;
+				}
+
+				const fallback = result.content?.[0]?.text ?? "searched";
+				text.setText(
+					`  ${theme.fg("dim", String(fallback).slice(0, 120))}`,
+				);
+				return text;
+			},
+		});
+	}
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "test"]
+}