hook-creator

name	hook-creator
description	Create and configure Codex hooks for customizing agent behavior. Use when the user wants to (1) create a new hook, (2) configure automatic formatting, logging, or notifications, (3) add file protection or custom permissions, (4) set up pre/post tool execution actions, or (5) asks about hook events like PreToolUse, PostToolUse, Notification, etc.

Hook Creator

Create Codex hooks that execute shell commands at specific lifecycle events.

Hook Creation Workflow

1. Identify the use case - Determine what the hook should accomplish
2. Select the appropriate event - Choose from available hook events (see references/hook-events.md)
3. Design the hook command - Write shell command that processes JSON input from stdin
4. Configure the matcher - Set tool/event filter (use * for all, or specific tool names like Bash, Edit|Write)
5. Choose storage location - User settings (~/.codex/settings.json) or project (.codex/settings.json)
6. Test the hook - Verify behavior with a simple test case

Hook Configuration Structure

{
  "hooks": {
    "<EventName>": [
      {
        "matcher": "<ToolPattern>",
        "hooks": [
          {
            "type": "command",
            "command": "<shell-command>"
          }
        ]
      }
    ]
  }
}

Common Patterns

Reading Input Data

Hooks receive JSON via stdin. Use jq to extract fields:

# Extract tool input field
jq -r '.tool_input.file_path'

# Extract with fallback
jq -r '.tool_input.description // "No description"'

# Conditional processing
jq -r 'if .tool_input.file_path then .tool_input.file_path else empty end'

Exit Codes for PreToolUse

• 0 - Allow the tool to proceed
• 2 - Block the tool and provide feedback to Codex

Matcher Patterns

• * - Match all tools
• Bash - Match only Bash tool
• Edit|Write - Match Edit or Write tools
• Read - Match Read tool

Quick Examples

Log all bash commands:

jq -r '"\(.tool_input.command)"' >> ~/.codex/bash-log.txt

Auto-format TypeScript after edit:

jq -r '.tool_input.file_path' | { read f; [[ "$f" == *.ts ]] && npx prettier --write "$f"; }

Block edits to .env files:

python3 -c "import json,sys; p=json.load(sys.stdin).get('tool_input',{}).get('file_path',''); sys.exit(2 if '.env' in p else 0)"

Resources

• Hook Events Reference: See references/hook-events.md for detailed event documentation with input/output schemas
• Example Configurations: See references/examples.md for complete, tested hook configurations