Choose the event

Hook events cover sessions, tool calls, compaction, prompts, stops, and subagent lifecycle points. Select the narrowest event that represents the invariant you need to enforce or observe.

• PreToolUse: Validate before execution
• PostToolUse: Observe completed work
• SessionStart: Initialize session context

Match narrowly

Use a regular-expression matcher to limit supported events to relevant tools or event values. Broad hooks increase latency and can create surprising behavior.

[[hooks.PostToolUse]]
matcher = "^apply_patch
    

      
The interactive Codex course
Learn OpenAI Codex by doing
Build practical Codex skills through original modules, simulations, configuration builders, and source-linked guidance.
      
Browse the complete Codex curriculum.
    
  quot;

[[hooks.PostToolUse.hooks]]
type = "command"
command = "npm run lint"
timeout = 60

Design exit behavior

Return success for an accepted event and a clear non-zero exit for a blocked invariant. Keep stdout concise and send diagnostic detail to a log when appropriate.

#!/usr/bin/env bash
set -euo pipefail
npm run lint -- --quiet

Security and performance

Treat hook input as untrusted, avoid interpolating unchecked values into a shell, and never log secrets. Measure cost before attaching expensive commands to frequent events.