@vaclav-synacek/pi-coding-agent-termux 0.45.7

package/examples/README.md

@@ -0,0 +1,24 @@
+# Examples
+
+Example code for pi-coding-agent SDK and extensions.
+
+## Directories
+
+### [sdk/](sdk/)
+Programmatic usage via `createAgentSession()`. Shows how to customize models, prompts, tools, extensions, and session management.
+
+### [extensions/](extensions/)
+Example extensions demonstrating:
+- Lifecycle event handlers (tool interception, safety gates, context modifications)
+- Custom tools (todo lists, questions, subagents, output truncation)
+- Commands and keyboard shortcuts
+- Custom UI (footers, headers, editors, overlays)
+- Git integration (checkpoints, auto-commit)
+- System prompt modifications and custom compaction
+- External integrations (SSH, file watchers, system theme sync)
+
+## Documentation
+
+- [SDK Reference](sdk/README.md)
+- [Extensions Documentation](../docs/extensions.md)
+- [Skills Documentation](../docs/skills.md)

package/examples/extensions/README.md

@@ -0,0 +1,168 @@
+# Extension Examples
+
+Example extensions for pi-coding-agent.
+
+## Usage
+
+```bash
+# Load an extension with --extension flag
+pi --extension examples/extensions/permission-gate.ts
+
+# Or copy to extensions directory for auto-discovery
+cp permission-gate.ts ~/.pi/agent/extensions/
+```
+
+## Examples
+
+### Lifecycle & Safety
+
+| Extension | Description |
+|-----------|-------------|
+| `permission-gate.ts` | Prompts for confirmation before dangerous bash commands (rm -rf, sudo, etc.) |
+| `protected-paths.ts` | Blocks writes to protected paths (.env, .git/, node_modules/) |
+| `confirm-destructive.ts` | Confirms before destructive session actions (clear, switch, fork) |
+| `dirty-repo-guard.ts` | Prevents session changes with uncommitted git changes |
+| `sandbox/` | OS-level sandboxing using `@anthropic-ai/sandbox-runtime` with per-project config |
+
+### Custom Tools
+
+| Extension | Description |
+|-----------|-------------|
+| `todo.ts` | Todo list tool + `/todos` command with custom rendering and state persistence |
+| `hello.ts` | Minimal custom tool example |
+| `question.ts` | Demonstrates `ctx.ui.select()` for asking the user questions with custom UI |
+| `questionnaire.ts` | Multi-question input with tab bar navigation between questions |
+| `tool-override.ts` | Override built-in tools (e.g., add logging/access control to `read`) |
+| `truncated-tool.ts` | Wraps ripgrep with proper output truncation (50KB/2000 lines) |
+| `ssh.ts` | Delegate all tools to a remote machine via SSH using pluggable operations |
+| `subagent/` | Delegate tasks to specialized subagents with isolated context windows |
+
+### Commands & UI
+
+| Extension | Description |
+|-----------|-------------|
+| `preset.ts` | Named presets for model, thinking level, tools, and instructions via `--preset` flag and `/preset` command |
+| `plan-mode/` | Claude Code-style plan mode for read-only exploration with `/plan` command and step tracking |
+| `tools.ts` | Interactive `/tools` command to enable/disable tools with session persistence |
+| `handoff.ts` | Transfer context to a new focused session via `/handoff <goal>` |
+| `qna.ts` | Extracts questions from last response into editor via `ctx.ui.setEditorText()` |
+| `status-line.ts` | Shows turn progress in footer via `ctx.ui.setStatus()` with themed colors |
+| `model-status.ts` | Shows model changes in status bar via `model_select` hook |
+| `snake.ts` | Snake game with custom UI, keyboard handling, and session persistence |
+| `send-user-message.ts` | Demonstrates `pi.sendUserMessage()` for sending user messages from extensions |
+| `timed-confirm.ts` | Demonstrates AbortSignal for auto-dismissing `ctx.ui.confirm()` and `ctx.ui.select()` dialogs |
+| `modal-editor.ts` | Custom vim-like modal editor via `ctx.ui.setEditorComponent()` |
+| `rainbow-editor.ts` | Animated rainbow text effect via custom editor |
+| `notify.ts` | Desktop notifications via OSC 777 when agent finishes (Ghostty, iTerm2, WezTerm) |
+| `summarize.ts` | Summarize conversation with GPT-5.2 and show in transient UI |
+| `custom-footer.ts` | Custom footer with git branch and token stats via `ctx.ui.setFooter()` |
+| `custom-header.ts` | Custom header via `ctx.ui.setHeader()` |
+| `overlay-test.ts` | Test overlay compositing with inline text inputs and edge cases |
+| `overlay-qa-tests.ts` | Comprehensive overlay QA tests: anchors, margins, stacking, overflow, animation |
+| `doom-overlay/` | DOOM game running as an overlay at 35 FPS (demonstrates real-time game rendering) |
+| `shutdown-command.ts` | Adds `/quit` command demonstrating `ctx.shutdown()` |
+| `interactive-shell.ts` | Run interactive commands (vim, htop) with full terminal via `user_bash` hook |
+
+### Git Integration
+
+| Extension | Description |
+|-----------|-------------|
+| `git-checkpoint.ts` | Creates git stash checkpoints at each turn for code restoration on fork |
+| `auto-commit-on-exit.ts` | Auto-commits on exit using last assistant message for commit message |
+
+### System Prompt & Compaction
+
+| Extension | Description |
+|-----------|-------------|
+| `pirate.ts` | Demonstrates `systemPromptAppend` to dynamically modify system prompt |
+| `claude-rules.ts` | Scans `.claude/rules/` folder and lists rules in system prompt |
+| `custom-compaction.ts` | Custom compaction that summarizes entire conversation |
+
+### System Integration
+
+| Extension | Description |
+|-----------|-------------|
+| `mac-system-theme.ts` | Syncs pi theme with macOS dark/light mode |
+
+### External Dependencies
+
+| Extension | Description |
+|-----------|-------------|
+| `chalk-logger.ts` | Uses chalk from parent node_modules (demonstrates jiti module resolution) |
+| `with-deps/` | Extension with its own package.json and dependencies |
+| `file-trigger.ts` | Watches a trigger file and injects contents into conversation |
+
+## Writing Extensions
+
+See [docs/extensions.md](../../docs/extensions.md) for full documentation.
+
+```typescript
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+export default function (pi: ExtensionAPI) {
+  // Subscribe to lifecycle events
+  pi.on("tool_call", async (event, ctx) => {
+    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
+      const ok = await ctx.ui.confirm("Dangerous!", "Allow rm -rf?");
+      if (!ok) return { block: true, reason: "Blocked by user" };
+    }
+  });
+
+  // Register custom tools
+  pi.registerTool({
+    name: "greet",
+    label: "Greeting",
+    description: "Generate a greeting",
+    parameters: Type.Object({
+      name: Type.String({ description: "Name to greet" }),
+    }),
+    async execute(toolCallId, params, onUpdate, ctx, signal) {
+      return {
+        content: [{ type: "text", text: `Hello, ${params.name}!` }],
+        details: {},
+      };
+    },
+  });
+
+  // Register commands
+  pi.registerCommand("hello", {
+    description: "Say hello",
+    handler: async (args, ctx) => {
+      ctx.ui.notify("Hello!", "info");
+    },
+  });
+}
+```
+
+## Key Patterns
+
+**Use StringEnum for string parameters** (required for Google API compatibility):
+```typescript
+import { StringEnum } from "@mariozechner/pi-ai";
+
+// Good
+action: StringEnum(["list", "add"] as const)
+
+// Bad - doesn't work with Google
+action: Type.Union([Type.Literal("list"), Type.Literal("add")])
+```
+
+**State persistence via details:**
+```typescript
+// Store state in tool result details for proper forking support
+return {
+  content: [{ type: "text", text: "Done" }],
+  details: { todos: [...todos], nextId },  // Persisted in session
+};
+
+// Reconstruct on session events
+pi.on("session_start", async (_event, ctx) => {
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type === "message" && entry.message.toolName === "my_tool") {
+      const details = entry.message.details;
+      // Reconstruct state from details
+    }
+  }
+});
+```

package/examples/extensions/auto-commit-on-exit.ts

@@ -0,0 +1,49 @@
+/**
+ * Auto-Commit on Exit Extension
+ *
+ * Automatically commits changes when the agent exits.
+ * Uses the last assistant message to generate a commit message.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_shutdown", async (_event, ctx) => {
+		// Check for uncommitted changes
+		const { stdout: status, code } = await pi.exec("git", ["status", "--porcelain"]);
+
+		if (code !== 0 || status.trim().length === 0) {
+			// Not a git repo or no changes
+			return;
+		}
+
+		// Find the last assistant message for commit context
+		const entries = ctx.sessionManager.getEntries();
+		let lastAssistantText = "";
+		for (let i = entries.length - 1; i >= 0; i--) {
+			const entry = entries[i];
+			if (entry.type === "message" && entry.message.role === "assistant") {
+				const content = entry.message.content;
+				if (Array.isArray(content)) {
+					lastAssistantText = content
+						.filter((c): c is { type: "text"; text: string } => c.type === "text")
+						.map((c) => c.text)
+						.join("\n");
+				}
+				break;
+			}
+		}
+
+		// Generate a simple commit message
+		const firstLine = lastAssistantText.split("\n")[0] || "Work in progress";
+		const commitMessage = `[pi] ${firstLine.slice(0, 50)}${firstLine.length > 50 ? "..." : ""}`;
+
+		// Stage and commit
+		await pi.exec("git", ["add", "-A"]);
+		const { code: commitCode } = await pi.exec("git", ["commit", "-m", commitMessage]);
+
+		if (commitCode === 0 && ctx.hasUI) {
+			ctx.ui.notify(`Auto-committed: ${commitMessage}`, "info");
+		}
+	});
+}

package/examples/extensions/chalk-logger.ts

@@ -0,0 +1,26 @@
+/**
+ * Example extension that uses a 3rd party dependency (chalk).
+ * Tests that jiti can resolve npm modules correctly.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import chalk from "chalk";
+
+export default function (pi: ExtensionAPI) {
+	// Log with colors using chalk
+	console.log(`${chalk.green("✓")} ${chalk.bold("chalk-logger extension loaded")}`);
+
+	pi.on("agent_start", async () => {
+		console.log(`${chalk.blue("[chalk-logger]")} Agent starting`);
+	});
+
+	pi.on("tool_call", async (event) => {
+		console.log(`${chalk.yellow("[chalk-logger]")} Tool: ${chalk.cyan(event.toolName)}`);
+		return undefined;
+	});
+
+	pi.on("agent_end", async (event) => {
+		const count = event.messages.length;
+		console.log(`${chalk.green("[chalk-logger]")} Done with ${chalk.bold(String(count))} messages`);
+	});
+}

package/examples/extensions/claude-rules.ts

@@ -0,0 +1,86 @@
+/**
+ * Claude Rules Extension
+ *
+ * Scans the project's .claude/rules/ folder for rule files and lists them
+ * in the system prompt. The agent can then use the read tool to load
+ * specific rules when needed.
+ *
+ * Best practices for .claude/rules/:
+ * - Keep rules focused: Each file should cover one topic (e.g., testing.md, api-design.md)
+ * - Use descriptive filenames: The filename should indicate what the rules cover
+ * - Use conditional rules sparingly: Only add paths frontmatter when rules truly apply to specific file types
+ * - Organize with subdirectories: Group related rules (e.g., frontend/, backend/)
+ *
+ * Usage:
+ * 1. Copy this file to ~/.pi/agent/extensions/ or your project's .pi/extensions/
+ * 2. Create .claude/rules/ folder in your project root
+ * 3. Add .md files with your rules
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Recursively find all .md files in a directory
+ */
+function findMarkdownFiles(dir: string, basePath: string = ""): string[] {
+	const results: string[] = [];
+
+	if (!fs.existsSync(dir)) {
+		return results;
+	}
+
+	const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+	for (const entry of entries) {
+		const relativePath = basePath ? `${basePath}/${entry.name}` : entry.name;
+
+		if (entry.isDirectory()) {
+			results.push(...findMarkdownFiles(path.join(dir, entry.name), relativePath));
+		} else if (entry.isFile() && entry.name.endsWith(".md")) {
+			results.push(relativePath);
+		}
+	}
+
+	return results;
+}
+
+export default function claudeRulesExtension(pi: ExtensionAPI) {
+	let ruleFiles: string[] = [];
+	let rulesDir: string = "";
+
+	// Scan for rules on session start
+	pi.on("session_start", async (_event, ctx) => {
+		rulesDir = path.join(ctx.cwd, ".claude", "rules");
+		ruleFiles = findMarkdownFiles(rulesDir);
+
+		if (ruleFiles.length > 0) {
+			ctx.ui.notify(`Found ${ruleFiles.length} rule(s) in .claude/rules/`, "info");
+		}
+	});
+
+	// Append available rules to system prompt
+	pi.on("before_agent_start", async (event) => {
+		if (ruleFiles.length === 0) {
+			return;
+		}
+
+		const rulesList = ruleFiles.map((f) => `- .claude/rules/${f}`).join("\n");
+
+		return {
+			systemPrompt:
+				event.systemPrompt +
+				`
+
+## Project Rules
+
+The following project rules are available in .claude/rules/:
+
+${rulesList}
+
+When working on tasks related to these rules, use the read tool to load the relevant rule files for guidance.
+`,
+		};
+	});
+}

package/examples/extensions/confirm-destructive.ts

@@ -0,0 +1,59 @@
+/**
+ * Confirm Destructive Actions Extension
+ *
+ * Prompts for confirmation before destructive session actions (clear, switch, branch).
+ * Demonstrates how to cancel session events using the before_* events.
+ */
+
+import type { ExtensionAPI, SessionBeforeSwitchEvent, SessionMessageEntry } from "@mariozechner/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_before_switch", async (event: SessionBeforeSwitchEvent, ctx) => {
+		if (!ctx.hasUI) return;
+
+		if (event.reason === "new") {
+			const confirmed = await ctx.ui.confirm(
+				"Clear session?",
+				"This will delete all messages in the current session.",
+			);
+
+			if (!confirmed) {
+				ctx.ui.notify("Clear cancelled", "info");
+				return { cancel: true };
+			}
+			return;
+		}
+
+		// reason === "resume" - check if there are unsaved changes (messages since last assistant response)
+		const entries = ctx.sessionManager.getEntries();
+		const hasUnsavedWork = entries.some(
+			(e): e is SessionMessageEntry => e.type === "message" && e.message.role === "user",
+		);
+
+		if (hasUnsavedWork) {
+			const confirmed = await ctx.ui.confirm(
+				"Switch session?",
+				"You have messages in the current session. Switch anyway?",
+			);
+
+			if (!confirmed) {
+				ctx.ui.notify("Switch cancelled", "info");
+				return { cancel: true };
+			}
+		}
+	});
+
+	pi.on("session_before_fork", async (event, ctx) => {
+		if (!ctx.hasUI) return;
+
+		const choice = await ctx.ui.select(`Fork from entry ${event.entryId.slice(0, 8)}?`, [
+			"Yes, create fork",
+			"No, stay in current session",
+		]);
+
+		if (choice !== "Yes, create fork") {
+			ctx.ui.notify("Fork cancelled", "info");
+			return { cancel: true };
+		}
+	});
+}

package/examples/extensions/custom-compaction.ts

@@ -0,0 +1,114 @@
+/**
+ * Custom Compaction Extension
+ *
+ * Replaces the default compaction behavior with a full summary of the entire context.
+ * Instead of keeping the last 20k tokens of conversation turns, this extension:
+ * 1. Summarizes ALL messages (messagesToSummarize + turnPrefixMessages)
+ * 2. Discards all old turns completely, keeping only the summary
+ *
+ * This example also demonstrates using a different model (Gemini Flash) for summarization,
+ * which can be cheaper/faster than the main conversation model.
+ *
+ * Usage:
+ *   pi --extension examples/extensions/custom-compaction.ts
+ */
+
+import { complete, getModel } from "@mariozechner/pi-ai";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { convertToLlm, serializeConversation } from "@mariozechner/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_before_compact", async (event, ctx) => {
+		ctx.ui.notify("Custom compaction extension triggered", "info");
+
+		const { preparation, branchEntries: _, signal } = event;
+		const { messagesToSummarize, turnPrefixMessages, tokensBefore, firstKeptEntryId, previousSummary } = preparation;
+
+		// Use Gemini Flash for summarization (cheaper/faster than most conversation models)
+		const model = getModel("google", "gemini-2.5-flash");
+		if (!model) {
+			ctx.ui.notify(`Could not find Gemini Flash model, using default compaction`, "warning");
+			return;
+		}
+
+		// Resolve API key for the summarization model
+		const apiKey = await ctx.modelRegistry.getApiKey(model);
+		if (!apiKey) {
+			ctx.ui.notify(`No API key for ${model.provider}, using default compaction`, "warning");
+			return;
+		}
+
+		// Combine all messages for full summary
+		const allMessages = [...messagesToSummarize, ...turnPrefixMessages];
+
+		ctx.ui.notify(
+			`Custom compaction: summarizing ${allMessages.length} messages (${tokensBefore.toLocaleString()} tokens) with ${model.id}...`,
+			"info",
+		);
+
+		// Convert messages to readable text format
+		const conversationText = serializeConversation(convertToLlm(allMessages));
+
+		// Include previous summary context if available
+		const previousContext = previousSummary ? `\n\nPrevious session summary for context:\n${previousSummary}` : "";
+
+		// Build messages that ask for a comprehensive summary
+		const summaryMessages = [
+			{
+				role: "user" as const,
+				content: [
+					{
+						type: "text" as const,
+						text: `You are a conversation summarizer. Create a comprehensive summary of this conversation that captures:${previousContext}
+
+1. The main goals and objectives discussed
+2. Key decisions made and their rationale
+3. Important code changes, file modifications, or technical details
+4. Current state of any ongoing work
+5. Any blockers, issues, or open questions
+6. Next steps that were planned or suggested
+
+Be thorough but concise. The summary will replace the ENTIRE conversation history, so include all information needed to continue the work effectively.
+
+Format the summary as structured markdown with clear sections.
+
+<conversation>
+${conversationText}
+</conversation>`,
+					},
+				],
+				timestamp: Date.now(),
+			},
+		];
+
+		try {
+			// Pass signal to honor abort requests (e.g., user cancels compaction)
+			const response = await complete(model, { messages: summaryMessages }, { apiKey, maxTokens: 8192, signal });
+
+			const summary = response.content
+				.filter((c): c is { type: "text"; text: string } => c.type === "text")
+				.map((c) => c.text)
+				.join("\n");
+
+			if (!summary.trim()) {
+				if (!signal.aborted) ctx.ui.notify("Compaction summary was empty, using default compaction", "warning");
+				return;
+			}
+
+			// Return compaction content - SessionManager adds id/parentId
+			// Use firstKeptEntryId from preparation to keep recent messages
+			return {
+				compaction: {
+					summary,
+					firstKeptEntryId,
+					tokensBefore,
+				},
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			ctx.ui.notify(`Compaction failed: ${message}`, "error");
+			// Fall back to default compaction on error
+			return;
+		}
+	});
+}

package/examples/extensions/custom-footer.ts

@@ -0,0 +1,64 @@
+/**
+ * Custom Footer Extension - demonstrates ctx.ui.setFooter()
+ *
+ * footerData exposes data not otherwise accessible:
+ * - getGitBranch(): current git branch
+ * - getExtensionStatuses(): texts from ctx.ui.setStatus()
+ *
+ * Token stats come from ctx.sessionManager/ctx.model (already accessible).
+ */
+
+import type { AssistantMessage } from "@mariozechner/pi-ai";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+
+export default function (pi: ExtensionAPI) {
+	let enabled = false;
+
+	pi.registerCommand("footer", {
+		description: "Toggle custom footer",
+		handler: async (_args, ctx) => {
+			enabled = !enabled;
+
+			if (enabled) {
+				ctx.ui.setFooter((tui, theme, footerData) => {
+					const unsub = footerData.onBranchChange(() => tui.requestRender());
+
+					return {
+						dispose: unsub,
+						invalidate() {},
+						render(width: number): string[] {
+							// Compute tokens from ctx (already accessible to extensions)
+							let input = 0,
+								output = 0,
+								cost = 0;
+							for (const e of ctx.sessionManager.getBranch()) {
+								if (e.type === "message" && e.message.role === "assistant") {
+									const m = e.message as AssistantMessage;
+									input += m.usage.input;
+									output += m.usage.output;
+									cost += m.usage.cost.total;
+								}
+							}
+
+							// Get git branch (not otherwise accessible)
+							const branch = footerData.getGitBranch();
+							const fmt = (n: number) => (n < 1000 ? `${n}` : `${(n / 1000).toFixed(1)}k`);
+
+							const left = theme.fg("dim", `↑${fmt(input)} ↓${fmt(output)} $${cost.toFixed(3)}`);
+							const branchStr = branch ? ` (${branch})` : "";
+							const right = theme.fg("dim", `${ctx.model?.id || "no-model"}${branchStr}`);
+
+							const pad = " ".repeat(Math.max(1, width - visibleWidth(left) - visibleWidth(right)));
+							return [truncateToWidth(left + pad + right, width)];
+						},
+					};
+				});
+				ctx.ui.notify("Custom footer enabled", "info");
+			} else {
+				ctx.ui.setFooter(undefined);
+				ctx.ui.notify("Default footer restored", "info");
+			}
+		},
+	});
+}

package/examples/extensions/custom-header.ts

@@ -0,0 +1,72 @@
+/**
+ * Custom Header Extension
+ *
+ * Demonstrates ctx.ui.setHeader() for replacing the built-in header
+ * (logo + keybinding hints) with a custom component showing the pi mascot.
+ */
+
+import type { ExtensionAPI, Theme } from "@mariozechner/pi-coding-agent";
+
+// --- PI MASCOT ---
+// Based on pi_mascot.ts - the pi agent character
+function getPiMascot(theme: Theme): string[] {
+	// --- COLORS ---
+	// 3b1b Blue: R=80, G=180, B=230
+	const piBlue = (text: string) => theme.fg("accent", text);
+	const white = (text: string) => text; // Use plain white (or theme.fg("text", text))
+	const black = (text: string) => theme.fg("dim", text); // Use dim for contrast
+
+	// --- GLYPHS ---
+	const BLOCK = "█";
+	const PUPIL = "▌"; // Vertical half-block for the pupil
+
+	// --- CONSTRUCTION ---
+
+	// 1. The Eye Unit: [White Full Block][Black Vertical Sliver]
+	// This creates the "looking sideways" effect
+	const eye = `${white(BLOCK)}${black(PUPIL)}`;
+
+	// 2. Line 1: The Eyes
+	// 5 spaces indent aligns them with the start of the legs
+	const lineEyes = `     ${eye}  ${eye}`;
+
+	// 3. Line 2: The Wide Top Bar (The "Overhang")
+	// 14 blocks wide for that serif-style roof
+	const lineBar = `  ${piBlue(BLOCK.repeat(14))}`;
+
+	// 4. Lines 3-6: The Legs
+	// Indented 5 spaces relative to the very left edge
+	// Leg width: 2 blocks | Gap: 4 blocks
+	const lineLeg = `     ${piBlue(BLOCK.repeat(2))}    ${piBlue(BLOCK.repeat(2))}`;
+
+	// --- ASSEMBLY ---
+	return ["", lineEyes, lineBar, lineLeg, lineLeg, lineLeg, lineLeg, ""];
+}
+
+export default function (pi: ExtensionAPI) {
+	// Set custom header immediately on load (if UI is available)
+	pi.on("session_start", async (_event, ctx) => {
+		if (ctx.hasUI) {
+			ctx.ui.setHeader((_tui, theme) => {
+				return {
+					render(_width: number): string[] {
+						const mascotLines = getPiMascot(theme);
+						// Add a subtitle with hint
+						const subtitle = theme.fg("muted", "   shitty coding agent");
+						return [...mascotLines, subtitle];
+					},
+					invalidate() {},
+				};
+			});
+		}
+	});
+
+	// Command to restore built-in header
+	pi.registerCommand("builtin-header", {
+		description: "Restore built-in header with keybinding hints",
+		handler: async (_args, ctx) => {
+			ctx.ui.setHeader(undefined);
+			ctx.ui.notify("Built-in header restored", "info");
+		},
+	});
+}