diff --git a/.codex/hooks/HOOKS-README.md b/.codex/hooks/HOOKS-README.md index cb08009..df752a3 100644 --- a/.codex/hooks/HOOKS-README.md +++ b/.codex/hooks/HOOKS-README.md @@ -3,30 +3,32 @@ Contains all the details, scripts, and instructions for the Codex CLI hooks. ## Hook Events Overview -Codex CLI provides **3 hooks** across two configuration systems: +Codex CLI provides **5 hooks** via hooks.json: | # | 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 | +| 1 | `SessionStart` | `SessionStart` | `hooks.json` | Runs once at session start — injects context + plays sound | +| 2 | `PreToolUse` | `PreToolUse` | `hooks.json` | Runs before a tool executes — plays sound | +| 3 | `PostToolUse` | `PostToolUse` | `hooks.json` | Runs after a tool completes — plays sound | +| 4 | `Stop` | `stop` | `hooks.json` | Runs when the session ends — plays sound | +| 5 | `UserPromptSubmit` | `UserPromptSubmit` | `hooks.json` | Runs when the user submits a prompt — plays sound | -> Hooks 2 and 3 require **Codex CLI v0.114.0+** with the hooks engine enabled: +> Hooks 1 and 4 require **Codex CLI v0.114.0+** with the hooks engine enabled. +> Hooks 2 and 3 require **Codex CLI v0.117.0+** with the hooks engine enabled. +> Hook 5 requires **Codex CLI v0.116.0+** with the hooks engine enabled: > ```bash > 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: +All hooks (hooks.json) are called with `--hook` flag: ``` python3 .codex/hooks/scripts/hooks.py --hook SessionStart +python3 .codex/hooks/scripts/hooks.py --hook PreToolUse +python3 .codex/hooks/scripts/hooks.py --hook PostToolUse python3 .codex/hooks/scripts/hooks.py --hook Stop +python3 .codex/hooks/scripts/hooks.py --hook UserPromptSubmit ``` ### SessionStart Context Injection @@ -37,8 +39,6 @@ The SessionStart hook outputs context to **stdout**, which feeds directly into t - 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. @@ -64,19 +64,12 @@ The hook script automatically detects and uses the appropriate audio player for ### Configuration Files -There are **three** configuration files: +There are **two** 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 +1. **`.codex/hooks.json`** — Registers `SessionStart`, `PreToolUse`, `PostToolUse`, `Stop`, and `UserPromptSubmit` hooks +2. **`.codex/hooks/config/hooks-config.json`** — Enable/disable individual hooks and logging -#### config.toml (agent-turn-complete hook) - -```toml -notify = ["python3", ".codex/hooks/scripts/hooks.py"] -``` - -#### hooks.json (SessionStart + Stop hooks) +#### hooks.json ```json { @@ -89,6 +82,22 @@ notify = ["python3", ".codex/hooks/scripts/hooks.py"] "timeout": 10 } ], + "PreToolUse": [ + { + "type": "shell", + "command": "python3 .codex/hooks/scripts/hooks.py --hook PreToolUse", + "statusMessage": "Running pre-tool-use hook...", + "timeout": 10 + } + ], + "PostToolUse": [ + { + "type": "shell", + "command": "python3 .codex/hooks/scripts/hooks.py --hook PostToolUse", + "statusMessage": "Running post-tool-use hook...", + "timeout": 10 + } + ], "Stop": [ { "type": "shell", @@ -96,6 +105,14 @@ notify = ["python3", ".codex/hooks/scripts/hooks.py"] "statusMessage": "Running session stop hook...", "timeout": 10 } + ], + "UserPromptSubmit": [ + { + "type": "shell", + "command": "python3 .codex/hooks/scripts/hooks.py --hook UserPromptSubmit", + "statusMessage": "Running user prompt submit hook...", + "timeout": 10 + } ] } } @@ -108,17 +125,21 @@ notify = ["python3", ".codex/hooks/scripts/hooks.py"] Edit `.codex/hooks/config/hooks-config.json`: ```json { - "disableAgentTurnCompleteHook": false, "disableSessionStartHook": false, + "disablePreToolUseHook": false, + "disablePostToolUseHook": false, "disableStopHook": false, + "disableUserPromptSubmitHook": 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 +- `disablePreToolUseHook`: Set to `true` to disable the pre-tool-use sound +- `disablePostToolUseHook`: Set to `true` to disable the post-tool-use sound - `disableStopHook`: Set to `true` to disable the session stop sound +- `disableUserPromptSubmitHook`: Set to `true` to disable the user prompt submit sound - `disableLogging`: Set to `true` to disable logging hook events to `.codex/hooks/logs/hooks-log.jsonl` ### Configuration Fallback @@ -136,9 +157,11 @@ Create or edit `.codex/hooks/config/hooks-config.local.json` for personal prefer ```json { - "disableAgentTurnCompleteHook": true, "disableSessionStartHook": false, + "disablePreToolUseHook": false, + "disablePostToolUseHook": false, "disableStopHook": true, + "disableUserPromptSubmitHook": false, "disableLogging": true } ``` @@ -154,6 +177,11 @@ Run the test suite: python3 -m unittest tests.test_hooks -v ``` +## Voice + +website used to generate sounds: https://elevenlabs.io/ +voice used: Adam - American, Dark and Tough + ## Future Extensibility This project can be extended by: