update Codex hooks reference 3→5 — replace agent-turn-complete with PreToolUse, PostToolUse, UserPromptSubmit
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Shayan Rais
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user