pi-hooks

Run user-defined hooks on all pi events.

Features

• Per-project hooks: Place hooks in .pi/pi-hooks/ in your project
• Global hooks: Place hooks in ~/.pi/pi-hooks/ for all projects
• All events: Hook into any pi Extension event
• Multiple hooks per event: Each hook lives in its own directory
• User confirmation: On hook failure, presents options to ignore or abort
• Output persistence: Hook output saved to temp file for reference
• Commands: List and configure hook settings
• Execution visibility: Toggle "show hook execution" to see notifications when hooks run
• Verbose output: See what hooks are doing via console.log/warn/error output

Supported Events

Each hook declares which event it listens to via the event export.

Hook	Trigger	Can Block?	Can Modify?	Use Cases
Agent
before_agent_start	Before LLM dispatch	✅ Yes	✅ Transform	Validate, inject context
agent_start	Agent starts	❌ No	Logging, setup
agent_start	Agent starts	❌ No	Logging, setup
agent_end	Agent completes	❌ No	Post-processing, logging
Turn
turn_start	Turn begins	❌ No	Per-turn setup
turn_end	Turn ends	❌ No	Per-turn cleanup
Message
message_start	Message starts	❌ No	Track message flow
message_update	Message updates (streaming)	❌ No	Monitor streaming
message_end	Message ends	❌ No	Track completion
Context
context	Before LLM call	❌ No	✅ Transform	Filter/inject messages
Tool Execution
tool_execution_start	Tool starts	❌ No	Track execution
tool_execution_update	Tool progress	❌ No	Monitor progress
tool_execution_end	Tool ends	❌ No	Track completion
tool_call	Before tool runs	✅ Yes	✅ Transform	Block/modify tool arguments
tool_result	After tool completes	❌ No	✅ Modify	Validate, log, modify output
Session
session_start	Session starts	❌ No	Setup, clear state
session_shutdown	Session ends	❌ No	Cleanup
session_before_switch	Before session switch	❌ No	Warn on dirty state
session_before_fork	Before fork	❌ No	Prepare fork
session_before_compact	Before compaction	❌ No	Customize summary
session_compact	After compaction	❌ No	Post-compact actions
session_before_tree	Before tree nav	❌ No	Prepare navigation
session_tree	After tree nav	❌ No	Post-nav actions
Model
model_select	Model changes	❌ No	Log model changes
Provider
before_provider_request	Before API call	❌ No	Debug payloads
after_provider_response	After API response	❌ No	Debug responses
Resource
resources_discover	Resources discovered	❌ No	Log resources
User Bash
user_bash	User runs ! or !!	❌ No	Intercept commands

Installation

pi install git:https://github.com/rwese/pi-hooks

Or copy the extension to ~/.pi/agent/extensions/pi-hooks/.

Creating Hooks

Location

Each hook lives in its own directory with an index.ts file that exports its event type.

Project-specific:

your-project/
├── .pi/
│   └── pi-hooks/
│       ├── my_input_validator/
│       │   └── index.ts
│       ├── block_dangerous/
│       │   └── index.ts
│       └── log_changes/
│           └── index.ts
└── ...

Global:

~/.pi/
└── pi-hooks/
    ├── my_input_validator/
    │   └── index.ts
    ├── block_dangerous/
    │   └── index.ts
    └── log_changes/
        └── index.ts

Hook Format

// ~/.pi/pi-hooks/log_changes/index.ts

// Declare which event this hook listens to
export const event = "tool_result" as const;

interface ToolResultPayload {
  event: "tool_result";
  toolCallId: string;
  toolName: string;       // "edit", "write", "bash", etc.
  input: object;           // Tool arguments
  content: Content[];     // Tool output
  details: object;        // Tool-specific details
  isError: boolean;
}

export default function logChangesHook(
  payload: ToolResultPayload
): boolean | void {
  const { toolName, input } = payload;

  // Log file modifications
  if (toolName === "edit" || toolName === "write") {
    const path = input.path as string;
    console.log(`[HOOK] ${toolName}: ${path}`);
  }

  return true; // Pass
  // return false; // Fail
}

before_agent_start Hook (Can Block & Transform)

// ~/.pi/pi-hooks/pre_dispatch/index.ts

export const event = "before_agent_start" as const;

interface BeforeAgentStartPayload {
  event: "before_agent_start";
  prompt: string;
  images: Image[];
  systemPrompt: string;
}

// Return false to block, or modified payload to transform
export default function preDispatchHook(
  payload: BeforeAgentStartPayload
): boolean | void | { prompt?: string; images?: Image[]; systemPrompt?: string } {
  const { prompt } = payload;

  // Auto-correct shorthand commands
  if (prompt.startsWith("test ")) {
    return {
      prompt: prompt.replace(/^test /, "test(unit): "),
    };
  }

  return true; // Pass unchanged
}

tool_call Hook (Can Block & Modify)

// ~/.pi/pi-hooks/block_dangerous/index.ts

export const event = "tool_call" as const;

interface ToolCallPayload {
  event: "tool_call";
  toolCallId: string;
  toolName: string;
  input: object;
}

// Return modified input to transform tool arguments
export default function blockDangerous(
  payload: ToolCallPayload
): boolean | void | { input: Record<string, unknown> } {
  const { toolName, input } = payload;

  // Block dangerous bash commands
  if (toolName === "bash") {
    const command = (input.command as string) || "";
    if (command.includes("rm -rf /")) {
      console.error("Blocking dangerous command!");
      return false; // Block
    }
  }

  // Modify tool arguments by returning new input
  if (toolName === "bash") {
    const command = input.command as string;
    if (!command.includes("--no-preserve-root")) {
      // Add safety flag
      return {
        passed: true,
        modified: true,
        input: {
          ...input,
          command: command + " --no-preserve-root",
        },
      };
    }
  }

  return true;
}

context Hook (Can Transform Messages)

// ~/.pi/pi-hooks/context_transformer/index.ts

export const event = "context" as const;

interface Message {
  role: "user" | "assistant" | "system";
  content: unknown;
}

interface ContextPayload {
  event: "context";
  messages: Message[];
}

export default function contextTransformerHook(
  payload: ContextPayload
): boolean | void | { messages: Message[] } {
  const { messages } = payload;

  // Example: Filter to last N messages
  const MAX = 20;
  if (messages.length > MAX) {
    return {
      passed: true,
      modified: true,
      messages: messages.slice(-MAX),
    };
  }

  return true; // Pass unchanged
}

tool_result Hook (Can Modify Output)

// ~/.pi/pi-hooks/validate_git/index.ts

export const event = "tool_result" as const;

interface ToolResultPayload {
  event: "tool_result";
  toolCallId: string;
  toolName: string;
  input: object;
  content: Content[];
  details: object;
  isError: boolean;
}

export default function validateGit(
  payload: ToolResultPayload
): boolean | void {
  const { toolName, content } = payload;

  // Validate git operations
  if (toolName === "bash") {
    const output = content
      .filter(c => c.type === "text")
      .map(c => c.text)
      .join("");

    if (output.includes("CONFLICT")) {
      console.error("[HOOK] Git conflict detected!");
    }
  }

  return true;
}

Example Hooks

See the examples/ directory for complete implementations:

Example	Event	Description
before_agent_start/	before_agent_start	Validates/modifies before LLM dispatch

| block_dangerous_commands/ | tool_call | Blocks dangerous bash commands | | log_file_modifications/ | tool_result | Logs all file modifications | | trim_tool_whitespace/ | tool_call | Trims trailing whitespace from input | | dirty_edit_guard/ | tool_call | Prevents edits to modified files | | context_transformer/ | context | Filters/transforms messages before LLM call | | agent_end/ | agent_end | Logs after agent completes |

Commands

Command	Description
/hooks:list	List available hooks (shows name and event type)
/hooks:show [on|off]	Toggle hook execution visibility
/hooks:verbose [on|off]	Toggle verbose hook output
/hooks:dirty-edit-clear	Clear tracked file states
/hooks:disable <event>	Disable an event type for this session
/hooks:enable <event>	Re-enable a disabled event type

Hook Return Values

Return	Meaning
true or undefined	Hook passed
false	Hook failed (blocked for blocking events)
throw new Error(msg)	Hook failed with message
{ prompt?, images?, systemPrompt? }	For before_agent_start: return transformed payload
{ input: {...} }	For tool_call: return transformed tool arguments
{ messages: [...] }	For context: return transformed messages
{ content, details, isError }	For tool_result: return modified result

Notes

• Hooks run with access to node_modules via npx tsx
• 30-second timeout per hook
• Hooks are skipped for non-interactive input (RPC, extensions)
• tool_call and before_agent_start can block execution
• Other hooks are informational only (can't block)
• Use /hooks:list to see which hooks are active
• Multiple hooks can listen to the same event type
• Project hooks take precedence over global hooks with the same name