oh-my-pi/packages/coding-agent/docs/hooks.md

omp can create hooks. Ask it to build one for your use case.

Hooks

Hooks are TypeScript modules that extend omp's behavior by subscribing to lifecycle events. They can intercept tool calls, prompt the user, modify results, inject messages, and more.

Key capabilities:

• User interaction - Hooks can prompt users via ctx.ui (select, confirm, input, notify)
• Custom UI components - Full TUI components with keyboard input via ctx.ui.custom()
• Custom slash commands - Register commands like /mycommand via pi.registerCommand()
• Event interception - Block or modify tool calls, inject context, customize compaction
• Session persistence - Store hook state that survives restarts via pi.appendEntry()

Example use cases:

• Permission gates (confirm before rm -rf, sudo, etc.)
• Git checkpointing (stash at each turn, restore on /branch)
• Path protection (block writes to .env, node_modules/)
• External integrations (file watchers, webhooks, CI triggers)
• Interactive tools (games, wizards, custom dialogs)

See examples/hooks/ for working implementations, including a snake game demonstrating custom UI.

Quick Start

Create ~/.omp/agent/hooks/pre/my-hook.ts (or project-local .omp/hooks/pre/):

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

export default function (pi: HookAPI) {
	pi.on("session_start", async (_event, ctx) => {
		ctx.ui.notify("Hook loaded!", "info");
	});

	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" };
		}
	});
}

Test with --hook flag:

omp --hook ./my-hook.ts

Hook Locations

Hooks are auto-discovered from config directories under hooks/:

Native (.omp, .pi) and Claude (.claude) use subdirectory structure:

• User-level:
  • Native: ~/.omp/agent/hooks/{pre,post}/*.ts (or ~/.pi/agent)
  • Claude: ~/.claude/hooks/{pre,post}/*.ts
• Project-level: .omp/hooks/{pre,post}/*.ts (or .pi, .claude)

Codex (.codex) uses flat structure with filename prefixes (pre-*.ts, post-*.ts):

• User-level: ~/.codex/hooks/*.ts
• Project-level: .codex/hooks/*.ts

Hooks can also be loaded from plugin manifests or explicitly via --hook.

Available Imports

Package	Purpose
@oh-my-pi/pi-coding-agent/hooks	Hook types (HookAPI, HookContext, events)
@oh-my-pi/pi-coding-agent	Components (BorderedLoader), utilities, type re-exports
@oh-my-pi/pi-ai	AI utilities (complete, message types)
@oh-my-pi/pi-tui	TUI components (CancellableLoader, etc.)

Node.js built-ins (node:fs, node:path, etc.) are also available.

Writing a Hook

A hook exports a default function that receives HookAPI:

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

export default function (pi: HookAPI) {
	// Subscribe to events
	pi.on("event_name", async (event, ctx) => {
		// Handle event
	});
}

Hooks are loaded via native Bun import, so TypeScript works without compilation.

Events

Lifecycle Overview

omp starts
  │
  └─► session_start
      │
      ▼
user sends prompt ─────────────────────────────────────────┐
  │                                                        │
  ├─► before_agent_start (can inject message)              │
  ├─► agent_start                                          │
  │                                                        │
  │   ┌─── turn (repeats while LLM calls tools) ───┐       │
  │   │                                            │       │
  │   ├─► turn_start                               │       │
  │   ├─► context (can modify messages)            │       │
  │   │                                            │       │
  │   │   LLM responds, may call tools:            │       │
  │   │     ├─► tool_call (can block)              │       │
  │   │     │   tool executes                      │       │
  │   │     └─► tool_result (can modify)           │       │
  │   │                                            │       │
  │   └─► turn_end                                 │       │
  │                                                        │
  └─► agent_end                                            │
                                                           │
user sends another prompt ◄────────────────────────────────┘

/new, /resume, or /fork
  ├─► session_before_switch (can cancel, has reason: "new" | "resume" | "fork")
  └─► session_switch (has reason: "new" | "resume" | "fork")

/branch
  ├─► session_before_branch (can cancel)
  └─► session_branch

/compact or auto-compaction
  ├─► session_before_compact (can cancel or customize)
  ├─► session.compacting (customize prompt/context)
  └─► session_compact

/tree navigation
  ├─► session_before_tree (can cancel or customize)
  └─► session_tree

exit (Ctrl+C, Ctrl+D)
  └─► session_shutdown

Session Events

session_start

Fired on initial session load.

pi.on("session_start", async (_event, ctx) => {
	ctx.ui.notify(`Session: ${ctx.sessionManager.getSessionFile() ?? "ephemeral"}`, "info");
});

session_before_switch / session_switch

Fired when starting a new session (/new), resuming (/resume), or forking (/fork).

pi.on("session_before_switch", async (event, ctx) => {
	// event.reason - "new" (starting fresh), "resume" (switching to existing), or "fork" (branch switch)
	// event.targetSessionFile - session we're switching to (only for "resume")

	if (event.reason === "new") {
		const ok = await ctx.ui.confirm("Clear?", "Delete all messages?");
		if (!ok) return { cancel: true };
	}

	return { cancel: true }; // Cancel the switch/new
});

pi.on("session_switch", async (event, ctx) => {
	// event.reason - "new", "resume", or "fork"
	// event.previousSessionFile - session we came from
});

session_before_branch / session_branch

Fired when branching via /branch.

pi.on("session_before_branch", async (event, ctx) => {
	// event.entryId - ID of the entry being branched from

	return { cancel: true }; // Cancel branch
	// OR
	return { skipConversationRestore: true }; // Branch but don't rewind messages
});

pi.on("session_branch", async (event, ctx) => {
	// event.previousSessionFile - previous session file
});

The skipConversationRestore option is useful for checkpoint hooks that restore code state separately.

session_before_compact / session.compacting / session_compact

Fired on compaction. See compaction.md for details.

pi.on("session_before_compact", async (event, ctx) => {
	const { preparation, branchEntries, customInstructions, signal } = event;

	// Cancel:
	return { cancel: true };

	// Custom summary:
	return {
		compaction: {
			summary: "...",
			firstKeptEntryId: preparation.firstKeptEntryId,
			tokensBefore: preparation.tokensBefore,
		},
	};
});

session.compacting

Fired after preparation but before the default summarizer runs. Use it to customize the prompt or add context when you are not returning a full compaction result from session_before_compact.

pi.on("session.compacting", async (event, ctx) => {
	// event.sessionId
	// event.messages - messages about to be summarized

	return {
		context: ["Additional context line"],
		prompt: "Custom compaction prompt...",
		preserveData: { source: "my-hook" },
	};
});

pi.on("session_compact", async (event, ctx) => {
	// event.compactionEntry - the saved compaction
	// event.fromExtension - whether hook provided it
});

session_before_tree / session_tree

Fired on /tree navigation. Always fires regardless of user's summarization choice. See compaction.md for details.

pi.on("session_before_tree", async (event, ctx) => {
	const { preparation, signal } = event;
	// preparation.targetId, oldLeafId, commonAncestorId, entriesToSummarize
	// preparation.userWantsSummary - whether user chose to summarize

	return { cancel: true };
	// OR provide custom summary (only used if userWantsSummary is true):
	return { summary: { summary: "...", details: {} } };
});

pi.on("session_tree", async (event, ctx) => {
	// event.newLeafId, oldLeafId, summaryEntry, fromExtension
});

session_shutdown

Fired on exit (Ctrl+C, Ctrl+D, SIGTERM).

pi.on("session_shutdown", async (_event, ctx) => {
	// Cleanup, save state, etc.
});

Agent Events

before_agent_start

Fired after user submits prompt, before agent loop. Can inject a persistent message.

pi.on("before_agent_start", async (event, ctx) => {
	// event.prompt - user's prompt text
	// event.images - attached images (if any)

	return {
		message: {
			customType: "my-hook",
			content: "Additional context for the LLM",
			display: true, // Show in TUI
		},
	};
});

The injected message is persisted as CustomMessageEntry and sent to the LLM.

agent_start / agent_end

Fired once per user prompt.

pi.on("agent_start", async (_event, ctx) => {});

pi.on("agent_end", async (event, ctx) => {
	// event.messages - messages from this prompt
});

turn_start / turn_end

Fired for each turn (one LLM response + tool calls).

pi.on("turn_start", async (event, ctx) => {
	// event.turnIndex, event.timestamp
});

pi.on("turn_end", async (event, ctx) => {
	// event.turnIndex
	// event.message - assistant's response
	// event.toolResults - tool results from this turn
});

context

Fired before each LLM call. Modify messages non-destructively (session unchanged).

pi.on("context", async (event, ctx) => {
	// event.messages - deep copy, safe to modify

	// Filter or transform messages
	const filtered = event.messages.filter((m) => !shouldPrune(m));
	return { messages: filtered };
});

Tool Events

tool_call

Fired before tool executes. Can block.

pi.on("tool_call", async (event, ctx) => {
	// event.toolName - "bash", "read", "write", "edit", etc.
	// event.toolCallId
	// event.input - tool parameters

	if (shouldBlock(event)) {
		return { block: true, reason: "Not allowed" };
	}
});

Tool inputs (common built-ins):

• bash: { command, timeout?, cwd?, head?, tail? }
• read: { path, offset?, limit?, lines? }
• write: { path, content }
• edit (replace mode): { path, old_text, new_text, all? }
• edit (patch mode): { path, op?, rename?, diff? }
• find: { pattern, hidden?, limit? }
• grep: { pattern, path?, glob?, type?, i?, pre?, post?, multiline?, limit?, offset? }

The edit input shape depends on the current edit variant (replace vs patch). Inspect event.input to see which schema is active.

Other tools (ask, browser, task, todo_write, fetch, web_search, python, notebook, lsp, ssh, calc) use their own schemas; inspect the tool prompt or src/tools/*.ts for details.

tool_result

Fired after tool executes (including errors). Can modify result.

Check event.isError to distinguish successful executions from failures.

pi.on("tool_result", async (event, ctx) => {
  // event.toolName, event.toolCallId, event.input
  // event.content - array of TextContent | ImageContent
  // event.details - tool-specific (see below)
  // event.isError - true if the tool threw an error

  if (event.isError) {
    // Handle error case
  }

  // Modify result:
  return { content: [...], details: {...}, isError: false };
});

Use event.toolName to narrow tool-specific details:

pi.on("tool_result", async (event, ctx) => {
	if (event.toolName === "bash") {
		// event.details is BashToolDetails | undefined
		const artifactId = event.details?.meta?.truncation?.artifactId;
		if (artifactId) {
			// Full output is stored under the artifact ID
		}
	}
});

HookContext

Every handler receives ctx: HookContext:

ctx.ui

UI methods for user interaction. Hooks can prompt users and even render custom TUI components.

Built-in dialogs:

// Select from options
const choice = await ctx.ui.select("Pick one:", ["A", "B", "C"]);
// Returns selected string or undefined if cancelled

// Confirm dialog
const ok = await ctx.ui.confirm("Delete?", "This cannot be undone");
// Returns true or false

// Text input (single line)
const name = await ctx.ui.input("Name:", "placeholder");
// Returns string or undefined if cancelled

// Multi-line editor (with Ctrl+G for external editor)
const text = await ctx.ui.editor("Edit prompt:", "prefilled text");
// Returns edited text or undefined if cancelled (Escape)
// Ctrl+Enter to submit, Ctrl+G to open $VISUAL or $EDITOR

// Notification (non-blocking)
ctx.ui.notify("Done!", "info"); // "info" | "warning" | "error"

// Set status text in footer (persistent until cleared)
ctx.ui.setStatus("my-hook", "Processing 5/10..."); // Set status
ctx.ui.setStatus("my-hook", undefined); // Clear status

// Set the core input editor text (pre-fill prompts, generated content)
ctx.ui.setEditorText("Generated prompt text here...");

// Get current editor text
const currentText = ctx.ui.getEditorText();

Status text notes:

• Multiple hooks can set their own status using unique keys
• Statuses are displayed on a single line in the footer, sorted alphabetically by key
• Text is sanitized (newlines/tabs replaced with spaces) and truncated to terminal width
• Use ctx.ui.theme to style status text with theme colors (see below)

Styling with theme colors:

Use ctx.ui.theme to apply consistent colors that respect the user's theme:

const theme = ctx.ui.theme;

// Foreground colors
ctx.ui.setStatus("my-hook", theme.fg("success", "✓") + theme.fg("dim", " Ready"));
ctx.ui.setStatus("my-hook", theme.fg("error", "✗") + theme.fg("dim", " Failed"));
ctx.ui.setStatus("my-hook", theme.fg("accent", "●") + theme.fg("dim", " Working..."));

// Available fg colors: accent, success, error, warning, muted, dim, text, and more
// See docs/theme.md for the full list of theme colors

See examples/hooks/status-line.ts for a complete example.

Custom components:

Show a custom TUI component with keyboard focus:

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

const result = await ctx.ui.custom((tui, theme, done) => {
	const loader = new BorderedLoader(tui, theme, "Working...");
	loader.onAbort = () => done(null);

	doWork(loader.signal)
		.then(done)
		.catch(() => done(null));

	return loader;
});

Your component can:

• Implement handleInput(data: string) to receive keyboard input
• Implement render(width: number): string[] to render lines
• Implement invalidate() to clear cached render
• Implement dispose() for cleanup when closed
• Call tui.requestRender() to trigger re-render
• Call done(result) when done to restore normal UI

See examples/hooks/qna.ts for a loader pattern and examples/hooks/snake.ts for a game. See tui.md for the full component API.

ctx.hasUI

false in print mode (-p) and JSON print mode. RPC mode provides UI via the host, so ctx.hasUI is true. Always check before using ctx.ui:

if (ctx.hasUI) {
  const choice = await ctx.ui.select(...);
} else {
  // Default behavior
}

ctx.cwd

Current working directory.

ctx.sessionManager

Read-only access to session state. See ReadonlySessionManager in src/session/session-manager.ts.

// Session info
ctx.sessionManager.getCwd(); // Working directory
ctx.sessionManager.getSessionDir(); // Session directory (~/.omp/agent/sessions)
ctx.sessionManager.getSessionId(); // Current session ID
ctx.sessionManager.getSessionFile(); // Session file path (undefined with --no-session)

// Entries
ctx.sessionManager.getEntries(); // All entries (excludes header)
ctx.sessionManager.getHeader(); // Session header entry
ctx.sessionManager.getEntry(id); // Specific entry by ID
ctx.sessionManager.getLabel(id); // Entry label (if any)

// Tree navigation
ctx.sessionManager.getBranch(); // Current branch (root to leaf)
ctx.sessionManager.getBranch(leafId); // Specific branch
ctx.sessionManager.getTree(); // Full tree structure
ctx.sessionManager.getLeafId(); // Current leaf entry ID
ctx.sessionManager.getLeafEntry(); // Current leaf entry

Use pi.sendMessage() or pi.appendEntry() for writes.

ctx.modelRegistry

Access to models and API keys:

// Get API key for a model
const apiKey = await ctx.modelRegistry.getApiKey(model);

// Get available models
const models = ctx.modelRegistry.getAvailable();

ctx.model

Current model, or undefined if none selected yet. Use for LLM calls in hooks:

if (ctx.model) {
	const apiKey = await ctx.modelRegistry.getApiKey(ctx.model);
	// Use with @oh-my-pi/pi-ai complete()
}

ctx.isIdle()

Returns true if the agent is not currently streaming:

if (ctx.isIdle()) {
	// Agent is not processing
}

ctx.abort()

Abort the current agent operation (fire-and-forget, does not wait):

ctx.abort();

ctx.hasQueuedMessages()

Check if there are messages queued (user typed while agent was streaming):

if (ctx.hasQueuedMessages()) {
	// Skip interactive prompt, let queued message take over
	return;
}

HookCommandContext (Slash Commands Only)

Slash command handlers receive HookCommandContext, which extends HookContext with session control methods. These methods are only safe in user-initiated commands because they can cause deadlocks if called from event handlers (which run inside the agent loop).

ctx.waitForIdle()

Wait for the agent to finish streaming:

await ctx.waitForIdle();
// Agent is now idle

ctx.newSession(options?)

Create a new session, optionally with initialization:

const result = await ctx.newSession({
	parentSession: ctx.sessionManager.getSessionFile(), // Track lineage
	setup: async (sm) => {
		// Initialize the new session
		sm.appendMessage({
			role: "user",
			content: [{ type: "text", text: "Context from previous session..." }],
			timestamp: Date.now(),
		});
	},
});

if (result.cancelled) {
	// A hook cancelled the new session
}

ctx.branch(entryId)

Branch from a specific entry, creating a new session file:

const result = await ctx.branch("entry-id-123");
if (!result.cancelled) {
	// Now in the branched session
}

ctx.navigateTree(targetId, options?)

Navigate to a different point in the session tree:

const result = await ctx.navigateTree("entry-id-456", {
	summarize: true, // Summarize the abandoned branch
});

HookAPI Methods

pi.on(event, handler)

Subscribe to events. See Events for all event types.

pi.sendMessage(message, options?)

Inject a message into the session. Creates a CustomMessageEntry that participates in the LLM context.

pi.sendMessage(
	{
		customType: "my-hook",      // Your hook's identifier
		content: "Message text",    // string or (TextContent | ImageContent)[]
		display: true,              // Show in TUI
		details: { ... },           // Optional metadata (not sent to LLM)
	},
	{ triggerTurn: true },        // Trigger a new LLM response if idle
);

Storage and timing:

• The message is appended to the session file immediately as a CustomMessageEntry
• If the agent is currently streaming, the message is queued and appended after the current turn
• If options.triggerTurn is true and the agent is idle, a new agent loop starts
• options.deliverAs chooses how to enqueue the message ("steer" or "followUp")

LLM context:

• CustomMessageEntry is converted to a user message when building context for the LLM
• Only content is sent to the LLM; details is for rendering/state only

TUI display:

• If display: true, the message appears in the chat with purple styling (customMessageBg, customMessageText, customMessageLabel theme colors)
• If display: false, the message is hidden from the TUI but still sent to the LLM
• Use pi.registerMessageRenderer() to customize how your messages render (see below)

pi.appendEntry(customType, data?)

Persist hook state. Creates CustomEntry (does NOT participate in LLM context).

// Save state
pi.appendEntry("my-hook-state", { count: 42 });

// Restore on reload
pi.on("session_start", async (_event, ctx) => {
	for (const entry of ctx.sessionManager.getEntries()) {
		if (entry.type === "custom" && entry.customType === "my-hook-state") {
			// Reconstruct from entry.data
		}
	}
});

pi.registerCommand(name, options)

Register a custom slash command:

pi.registerCommand("stats", {
	description: "Show session statistics",
	handler: async (args, ctx) => {
		// args = everything after /stats
		const count = ctx.sessionManager.getEntries().length;
		ctx.ui.notify(`${count} entries`, "info");
	},
});

For long-running commands (e.g., LLM calls), use ctx.ui.custom() with a loader. See examples/hooks/qna.ts.

To trigger the LLM after a command, call pi.sendMessage(..., { triggerTurn: true }).

pi.registerMessageRenderer(customType, renderer)

Register a custom TUI renderer for CustomMessageEntry messages with your customType. Without a custom renderer, messages display with default purple styling showing the content as-is.

import { Text } from "@oh-my-pi/pi-tui";

pi.registerMessageRenderer("my-hook", (message, options, theme) => {
	// message.content - the message content (string or content array)
	// message.details - your custom metadata
	// options.expanded - true if user pressed Ctrl+O

	const prefix = theme.fg("accent", `[${message.details?.label ?? "INFO"}] `);
	const text =
		typeof message.content === "string"
			? message.content
			: message.content.map((c) => (c.type === "text" ? c.text : "[image]")).join("");

	return new Text(prefix + theme.fg("text", text), 0, 0);
});

Renderer signature:

type HookMessageRenderer = (
	message: HookMessage,
	options: { expanded: boolean },
	theme: Theme
) => Component | undefined;

Return undefined to use default rendering. The returned component is wrapped in a styled Box by the TUI. See tui.md for component details.

pi.exec(command, args, options?)

Execute a shell command:

const result = await pi.exec("git", ["status"], {
	signal, // AbortSignal
	timeout, // Milliseconds
});

// result.stdout, result.stderr, result.code, result.killed

pi.logger / pi.typebox / pi.pi

• pi.logger is the shared logger (avoid console.* to keep the TUI clean)
• pi.typebox exposes @sinclair/typebox for schema definitions
• pi.pi exposes @oh-my-pi/pi-coding-agent exports (components, helpers)

Examples

Permission Gate

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

export default function (pi: HookAPI) {
	const dangerous = [/\brm\s+(-rf?|--recursive)/i, /\bsudo\b/i];

	pi.on("tool_call", async (event, ctx) => {
		if (event.toolName !== "bash") return;

		const cmd = event.input.command as string;
		if (dangerous.some((p) => p.test(cmd))) {
			if (!ctx.hasUI) {
				return { block: true, reason: "Dangerous (no UI)" };
			}
			const ok = await ctx.ui.confirm("Dangerous!", `Allow: ${cmd}?`);
			if (!ok) return { block: true, reason: "Blocked by user" };
		}
	});
}

Protected Paths

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

export default function (pi: HookAPI) {
	const protectedPaths = [".env", ".git/", "node_modules/"];

	pi.on("tool_call", async (event, ctx) => {
		if (event.toolName !== "write" && event.toolName !== "edit") return;

		const path = event.input.path as string;
		if (protectedPaths.some((p) => path.includes(p))) {
			ctx.ui.notify(`Blocked: ${path}`, "warning");
			return { block: true, reason: `Protected: ${path}` };
		}
	});
}

Git Checkpoint

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

export default function (pi: HookAPI) {
	const checkpoints = new Map<string, string>();
	let currentEntryId: string | undefined;

	pi.on("tool_result", async (_event, ctx) => {
		const leaf = ctx.sessionManager.getLeafEntry();
		if (leaf) currentEntryId = leaf.id;
	});

	pi.on("turn_start", async () => {
		const { stdout } = await pi.exec("git", ["stash", "create"]);
		if (stdout.trim() && currentEntryId) {
			checkpoints.set(currentEntryId, stdout.trim());
		}
	});

	pi.on("session_before_branch", async (event, ctx) => {
		const ref = checkpoints.get(event.entryId);
		if (!ref || !ctx.hasUI) return;

		const ok = await ctx.ui.confirm("Restore?", "Restore code to checkpoint?");
		if (ok) {
			await pi.exec("git", ["stash", "apply", ref]);
			ctx.ui.notify("Code restored", "info");
		}
	});

	pi.on("agent_end", () => checkpoints.clear());
}

Custom Command

See examples/hooks/snake.ts for a complete example with registerCommand(), ui.custom(), and session persistence.

Mode Behavior

Mode	UI Methods	Notes
Interactive	Full TUI	Normal operation
RPC	UI via RPC	Host handles UI, ctx.hasUI is true
Print (-p)	No-op (returns undefined/false)	Hooks run but can't prompt (ctx.hasUI=false)

In print mode (including JSON output), select() returns undefined, confirm() returns false, input() returns undefined, getEditorText() returns "", and setEditorText()/setStatus() are no-ops. Design hooks to handle this by checking ctx.hasUI.

Error Handling

• Hook errors are logged, agent continues
• tool_call errors block the tool (fail-safe)
• Errors display in UI with hook path and message
• If a hook hangs, use Ctrl+C to abort

Debugging

1. Open VS Code in hooks directory
2. Open JavaScript Debug Terminal (Ctrl+Shift+P → "JavaScript Debug Terminal")
3. Set breakpoints
4. Run omp --hook ./my-hook.ts