@vahor/pi-hooks

Run shell commands in response to pi events.

pi install npm:@vahor/pi-hooks

// .pi/hooks.json
{
  "hooks": {
    "agent_end": ["bun format", "bun typecheck"],
    "session_start": [{ "command": "echo 'session start'", "print": true }]
  }
}

Config locations

Configuration is loaded from both locations and merged recursively:

| Location | Scope | |----------|-------| | ~/.pi/agent/hooks.json | Global hooks | | .pi/hooks.json | Project hooks; overrides global values |

If neither file exists, the extension creates .pi/hooks.json with an empty config and a $schema field for editor validation.

Each entry can be a string (just the command) or an object:

| Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | command | string | Yes | – | Shell command to run | | cwd | string | No | project root | Working directory (relative) | | timeout | number | No | 30000 | Timeout in milliseconds | | print | boolean | No | true | Render command output in pi | | context | boolean | No | false | Add command output to the agent context | | interactive | boolean | No | false | Suspend pi's TUI and run with full terminal access. Use for commands like lazygit, vim, htop, or fzf. Output is not captured. |

Command output is rendered in pi when print or context is enabled. Interactive commands restore and fully redraw pi after they exit.

Available hooks

These correspond to pi lifecycle events.

| Hook | Description | |------|-------------| | session_start | Session initialized and ready | | session_before_switch | Before switching to a different session | | session_before_fork | Before forking the session | | session_before_compact | Before compacting session context | | session_compact | Session context compacted | | session_before_tree | Before generating the session tree | | session_tree | Session tree generated | | session_shutdown | Session is shutting down | | before_agent_start | Before the agent starts processing | | agent_start | Agent has started | | agent_end | Agent has finished | | turn_start | A new turn begins | | turn_end | The current turn ends | | message_start | A message (user or assistant) begins | | message_update | A message is updated in place | | message_end | A message is complete | | tool_execution_start | A tool execution begins | | tool_execution_update | Tool execution output is updated | | tool_execution_end | Tool execution finishes | | context | Context is provided to the model | | before_provider_request | Before sending a request to the model provider | | after_provider_response | After receiving a response from the model provider | | model_select | A model is selected | | thinking_level_select | Thinking level is selected | | tool_call | Assistant requests a tool call | | tool_result | Tool result is received | | input | User submits input | | resources_discover | Resources are discovered |