# 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 ~/.omp/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, branch)
`dirty-repo-guard.ts`	Prevents session changes with uncommitted git changes

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
`subagent/`	Delegate tasks to specialized subagents with isolated context windows

Commands & UI

Extension	Description
`plan-mode.ts`	Claude Code-style plan mode for read-only exploration with `/plan` command
`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
`thinking-note.ts`	Adds display-only supplemental UI below assistant thinking blocks
`snake.ts`	Snake game with custom UI, keyboard handling, and session persistence

Git Integration

Extension	Description
`git-checkpoint.ts`	Creates git stash checkpoints at each turn for code restoration on branch
`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
`custom-compaction.ts`	Custom compaction that summarizes entire conversation

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 for full documentation.

import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";

export default function (pi: ExtensionAPI) {
	const z = pi.zod;

	// 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: z.object({
			name: z.string().describe("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 z.enum for discriminated string tool args:

const { z } = pi.zod;

parameters: z.object({
	action: z.enum(["list", "add"]),
});

State persistence via details:

// Store state in tool result details for proper branching 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
		}
	}
});