claude-code-best-practice/.codex/hooks/HOOKS-README.md

HOOKS-README

Contains all the details, scripts, and instructions for the Codex CLI hooks.

Hook Events Overview

Codex CLI provides 3 hooks across two configuration systems:

#	Hook	Event Type	Config File	Description
1	agent-turn-complete	agent-turn-complete	config.toml	Runs when the Codex agent finishes responding
2	SessionStart	SessionStart	hooks.json	Runs once at session start — injects context + plays sound
3	Stop	stop	hooks.json	Runs when the session ends — plays sound

Hooks 2 and 3 require Codex CLI v0.114.0+ with the hooks engine enabled:

codex -c features.codex_hooks=true

How Hooks Are Called

agent-turn-complete hook (config.toml) — JSON passed as CLI argument:

python3 .codex/hooks/scripts/hooks.py '{"type":"agent-turn-complete"}'

SessionStart / Stop hooks (hooks.json) — called with --hook flag:

python3 .codex/hooks/scripts/hooks.py --hook SessionStart
python3 .codex/hooks/scripts/hooks.py --hook Stop

SessionStart Context Injection

The SessionStart hook outputs context to stdout, which feeds directly into the model's context window. This includes:

• Current date/time
• Git branch name
• Working tree status (clean or uncommitted changes)
• Working directory path

Key difference from Claude Code: Claude Code passes JSON via stdin, while Codex CLI passes it as a CLI argument. The new hooks.json system uses --hook flags.

Prerequisites

Before using hooks, ensure you have Python 3 installed on your system.

Required Software

All Platforms (Windows, macOS, Linux)

• Python 3: Required for running the hook script
• Verify installation: python3 --version

Installation Instructions:

• Windows: Download from python.org or install via winget install Python.Python.3
• macOS: Install via brew install python3 (requires Homebrew)
• Linux: Install via sudo apt install python3 (Ubuntu/Debian) or sudo yum install python3 (RHEL/CentOS)

Audio Players (Automatically Detected)

The hook script automatically detects and uses the appropriate audio player for your platform:

• macOS: Uses afplay (built-in, no installation needed)
• Linux: Uses paplay from pulseaudio-utils - install via sudo apt install pulseaudio-utils
• Windows: Uses built-in winsound module (included with Python)

Configuration Files

There are three configuration files:

1. .codex/config.toml — Registers the agent-turn-complete hook (via notify)
2. .codex/hooks.json — Registers SessionStart and Stop hooks (v0.114.0+)
3. .codex/hooks/config/hooks-config.json — Enable/disable individual hooks and logging

config.toml (agent-turn-complete hook)

notify = ["python3", ".codex/hooks/scripts/hooks.py"]

hooks.json (SessionStart + Stop hooks)

{
  "hooks": {
    "SessionStart": [
      {
        "type": "shell",
        "command": "python3 .codex/hooks/scripts/hooks.py --hook SessionStart",
        "statusMessage": "Initializing session hooks...",
        "timeout": 10
      }
    ],
    "Stop": [
      {
        "type": "shell",
        "command": "python3 .codex/hooks/scripts/hooks.py --hook Stop",
        "statusMessage": "Running session stop hook...",
        "timeout": 10
      }
    ]
  }
}

Configuring Hooks (Enable/Disable)

Disable Individual Hooks

Edit .codex/hooks/config/hooks-config.json:

{
  "disableAgentTurnCompleteHook": false,
  "disableSessionStartHook": false,
  "disableStopHook": false,
  "disableLogging": true
}

Configuration Options:

• disableAgentTurnCompleteHook: Set to true to disable the agent-turn-complete sound
• disableSessionStartHook: Set to true to disable the session start context injection and sound
• disableStopHook: Set to true to disable the session stop sound
• disableLogging: Set to true to disable logging hook events to .codex/hooks/logs/hooks-log.jsonl

Configuration Fallback

There are two configuration files:

1. .codex/hooks/config/hooks-config.json - The shared/default configuration that is committed to git
2. .codex/hooks/config/hooks-config.local.json - Your personal overrides (git-ignored)

The local config file (.local.json) takes precedence over the shared config, allowing each developer to customize their hook behavior without affecting the team.

Local Configuration (Personal Overrides)

Create or edit .codex/hooks/config/hooks-config.local.json for personal preferences:

{
  "disableAgentTurnCompleteHook": true,
  "disableSessionStartHook": false,
  "disableStopHook": true,
  "disableLogging": true
}

Logging

When logging is enabled ("disableLogging": false), hook events are logged to .codex/hooks/logs/hooks-log.jsonl in JSON Lines format. Each entry contains the full JSON payload received from Codex CLI.

Testing

Run the test suite:

python3 -m unittest tests.test_hooks -v

Future Extensibility

This project can be extended by:

1. Adding new entries to HOOK_SOUND_MAP in hooks.py
2. Adding corresponding sound files in .codex/hooks/sounds/
3. Adding toggle keys in hooks-config.json
4. Adding new hook entries in hooks.json