gilles/claude-code-best-practice
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updated codex hooks

Browse Source
This commit is contained in:
Shayan Rais
2026-05-16 23:55:53 +05:00
parent a77e223a6e
commit ac0d87d886
11 changed files with 103 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.codex/config.toml
-3
View File
@@ -1,5 +1,2 @@
sandbox_mode = "danger-full-access"
approval_policy = "never"
[features]
codex_hooks = true
.codex/hooks.json
+36
View File
@@ -25,6 +25,18 @@
]
}
],
"PermissionRequest": [
{
"hooks": [
{
"type": "command",
"command": "python3 .codex/hooks/scripts/hooks.py --hook PermissionRequest",
"timeout": 10,
"statusMessage": "Running permission request hook"
}
]
}
],
"PostToolUse": [
{
"hooks": [
@@ -60,6 +72,30 @@
}
]
}
],
"PreCompact": [
{
"hooks": [
{
"type": "command",
"command": "python3 .codex/hooks/scripts/hooks.py --hook PreCompact",
"timeout": 10,
"statusMessage": "Running pre-compact hook"
}
]
}
],
"PostCompact": [
{
"hooks": [
{
"type": "command",
"command": "python3 .codex/hooks/scripts/hooks.py --hook PostCompact",
"timeout": 10,
"statusMessage": "Running post-compact hook"
}
]
}
]
}
}
.codex/hooks/HOOKS-README.md
+44 -12
View File
@@ -3,22 +3,18 @@ Contains all the details, scripts, and instructions for the Codex CLI hooks.
## Hook Events Overview
Codex CLI provides **5 hooks** via hooks.json:
Codex CLI provides **8 hooks** via hooks.json:
| # | Hook | Event Type | Config File | Description |
|:-:|------|------------|-------------|-------------|
| 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 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
> ```
| 3 | `PermissionRequest` | `PermissionRequest` | `hooks.json` | Runs when Codex requests approval for a sensitive op — plays sound |
| 4 | `PostToolUse` | `PostToolUse` | `hooks.json` | Runs after a tool completes — plays sound |
| 5 | `Stop` | `stop` | `hooks.json` | Runs when the session ends — plays sound |
| 6 | `UserPromptSubmit` | `UserPromptSubmit` | `hooks.json` | Runs when the user submits a prompt — plays sound |
| 7 | `PreCompact` | `PreCompact` | `hooks.json` | Runs before context compaction — plays sound |
| 8 | `PostCompact` | `PostCompact` | `hooks.json` | Runs after context compaction — plays sound |
### How Hooks Are Called
@@ -26,9 +22,12 @@ 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 PermissionRequest
python3 .codex/hooks/scripts/hooks.py --hook PostToolUse
python3 .codex/hooks/scripts/hooks.py --hook Stop
python3 .codex/hooks/scripts/hooks.py --hook UserPromptSubmit
python3 .codex/hooks/scripts/hooks.py --hook PreCompact
python3 .codex/hooks/scripts/hooks.py --hook PostCompact
```
### SessionStart Context Injection
@@ -66,7 +65,7 @@ The hook script automatically detects and uses the appropriate audio player for
There are **two** configuration files:
1. **`.codex/hooks.json`** — Registers `SessionStart`, `PreToolUse`, `PostToolUse`, `Stop`, and `UserPromptSubmit` hooks
1. **`.codex/hooks.json`** — Registers `SessionStart`, `PreToolUse`, `PermissionRequest`, `PostToolUse`, `Stop`, `UserPromptSubmit`, `PreCompact`, and `PostCompact` hooks
2. **`.codex/hooks/config/hooks-config.json`** — Enable/disable individual hooks and logging
#### hooks.json
@@ -90,6 +89,14 @@ There are **two** configuration files:
"timeout": 10
}
],
"PermissionRequest": [
{
"type": "shell",
"command": "python3 .codex/hooks/scripts/hooks.py --hook PermissionRequest",
"statusMessage": "Running permission request hook...",
"timeout": 10
}
],
"PostToolUse": [
{
"type": "shell",
@@ -113,6 +120,22 @@ There are **two** configuration files:
"statusMessage": "Running user prompt submit hook...",
"timeout": 10
}
],
"PreCompact": [
{
"type": "shell",
"command": "python3 .codex/hooks/scripts/hooks.py --hook PreCompact",
"statusMessage": "Running pre-compact hook...",
"timeout": 10
}
],
"PostCompact": [
{
"type": "shell",
"command": "python3 .codex/hooks/scripts/hooks.py --hook PostCompact",
"statusMessage": "Running post-compact hook...",
"timeout": 10
}
]
}
}
@@ -127,9 +150,12 @@ Edit `.codex/hooks/config/hooks-config.json`:
{
"disableSessionStartHook": false,
"disablePreToolUseHook": false,
"disablePermissionRequestHook": false,
"disablePostToolUseHook": false,
"disableStopHook": false,
"disableUserPromptSubmitHook": false,
"disablePreCompactHook": false,
"disablePostCompactHook": false,
"disableLogging": true
}
```
@@ -137,9 +163,12 @@ Edit `.codex/hooks/config/hooks-config.json`:
**Configuration Options:**
- `disableSessionStartHook`: Set to `true` to disable the session start context injection and sound
- `disablePreToolUseHook`: Set to `true` to disable the pre-tool-use sound
- `disablePermissionRequestHook`: Set to `true` to disable the permission request 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
- `disablePreCompactHook`: Set to `true` to disable the pre-compact sound
- `disablePostCompactHook`: Set to `true` to disable the post-compact sound
- `disableLogging`: Set to `true` to disable logging hook events to `.codex/hooks/logs/hooks-log.jsonl`
### Configuration Fallback
@@ -159,9 +188,12 @@ Create or edit `.codex/hooks/config/hooks-config.local.json` for personal prefer
{
"disableSessionStartHook": false,
"disablePreToolUseHook": false,
"disablePermissionRequestHook": false,
"disablePostToolUseHook": false,
"disableStopHook": true,
"disableUserPromptSubmitHook": false,
"disablePreCompactHook": false,
"disablePostCompactHook": false,
"disableLogging": true
}
```
.codex/hooks/config/hooks-config.json
+3
View File
@@ -1,8 +1,11 @@
{
"disableSessionStartHook": false,
"disablePreToolUseHook": false,
"disablePermissionRequestHook": false,
"disablePostToolUseHook": false,
"disableStopHook": false,
"disableUserPromptSubmitHook": false,
"disablePreCompactHook": false,
"disablePostCompactHook": false,
"disableLogging": true
}
.codex/hooks/scripts/hooks.py
+20 -8
View File
@@ -3,12 +3,15 @@
Codex CLI Hook Handler
=============================================
This script handles hooks from Codex CLI and plays sounds.
Codex CLI supports 5 hooks:
Codex CLI supports 8 hooks:
1. SessionStart - via hooks.json (v0.114.0+)
2. PreToolUse - via hooks.json (v0.117.0+)
3. PostToolUse - via hooks.json (v0.117.0+)
4. Stop - via hooks.json (v0.114.0+)
5. UserPromptSubmit - via hooks.json (v0.116.0+)
3. PermissionRequest - via hooks.json (v0.122.0+)
4. PostToolUse - via hooks.json (v0.117.0+)
5. Stop - via hooks.json (v0.114.0+)
6. UserPromptSubmit - via hooks.json (v0.116.0+)
7. PreCompact - via hooks.json (v0.130.0+)
8. PostCompact - via hooks.json (v0.130.0+)
Input:
- All hooks use --hook <hook-name> flag via hooks.json
@@ -32,18 +35,24 @@ except ImportError:
HOOK_SOUND_MAP = {
"SessionStart": "SessionStart",
"PreToolUse": "PreToolUse",
"PermissionRequest": "PermissionRequest",
"PostToolUse": "PostToolUse",
"Stop": "Stop",
"UserPromptSubmit": "UserPromptSubmit",
"PreCompact": "PreCompact",
"PostCompact": "PostCompact",
}
# ===== HOOK EVENT TO CONFIG KEY MAPPING =====
HOOK_CONFIG_MAP = {
"SessionStart": "disableSessionStartHook",
"PreToolUse": "disablePreToolUseHook",
"PermissionRequest": "disablePermissionRequestHook",
"PostToolUse": "disablePostToolUseHook",
"Stop": "disableStopHook",
"UserPromptSubmit": "disableUserPromptSubmitHook",
"PreCompact": "disablePreCompactHook",
"PostCompact": "disablePostCompactHook",
}
@@ -311,12 +320,15 @@ def main():
"""
Main program - runs when Codex CLI triggers a hook.
Supports 5 hooks:
Supports 8 hooks:
1. SessionStart (hooks.json): Outputs context to stdout + plays sound
2. PreToolUse (hooks.json): Plays sound before a tool executes
3. PostToolUse (hooks.json): Plays sound after a tool completes
4. Stop (hooks.json): Plays sound on session end
5. UserPromptSubmit (hooks.json): Plays sound when user submits a prompt
3. PermissionRequest (hooks.json): Plays sound when approval is requested
4. PostToolUse (hooks.json): Plays sound after a tool completes
5. Stop (hooks.json): Plays sound on session end
6. UserPromptSubmit (hooks.json): Plays sound when user submits a prompt
7. PreCompact (hooks.json): Plays sound before context compaction
8. PostCompact (hooks.json): Plays sound after context compaction
"""
try:
event_type, input_data = parse_args(sys.argv[1:])
.codex/hooks/sounds/PermissionRequest/PermissionRequest.mp3
BIN
View File
Binary file not shown.
.codex/hooks/sounds/PermissionRequest/PermissionRequest.wav
BIN
View File
Binary file not shown.
.codex/hooks/sounds/PostCompact/PostCompact.mp3
BIN
View File
Binary file not shown.
.codex/hooks/sounds/PostCompact/PostCompact.wav
BIN
View File
Binary file not shown.
.codex/hooks/sounds/PreCompact/PreCompact.mp3
BIN
View File
Binary file not shown.
.codex/hooks/sounds/PreCompact/PreCompact.wav
BIN
View File
Binary file not shown.