Codex Hooks

codex-hooks

`codex-hooks` is a macOS-focused Python tool that replays a compatible subset of Claude-style command hooks for Codex by watching Codex session JSONL files.

This repository intentionally stays focused on hook reproduction. It does not own UI features such as desktop notifications or terminal title updates. Its job is only to decide when hooks should fire and which commands should run.

Current Compatibility

`codex-hooks` currently supports a compatible subset of Claude-style command hooks.

What works today:

• Reading ~/.codex/hooks.json
• Falling back to ~/.claude/settings.json
• Watching Codex session JSONL files
• Firing command hooks for TaskStarted, TaskComplete, and TurnAborted
• Reusing Claude hooks that only need shell execution plus stdin input

This works well for hooks such as:

• Desktop notifications
• Terminal or iTerm title updates
• Sound effects
• Shell scripts that perform direct side effects

What does not work today:

• Claude's full hook response protocol
• Hook stdout such as {"decision":"block","reason":"..."}
• Hooks that expect Claude to load a Skill automatically
• Hooks that depend on Claude-specific stdin fields
• Full Claude matcher and lifecycle compatibility

Install

git clone https://github.com/hatayama/codex-hooks.git
cd codex-hooks
python3 install.py
source ~/.zshrc

After installation, a `codex` shell function is added. It launches the real Codex CLI and starts a background session monitor at the same time.

To disable the wrapper temporarily:

CODEX_HOOKS_DISABLE=1 codex ...

Configuration Priority

1. ~/.codex/hooks.json
2. ~/.claude/settings.json

If `~/.codex/hooks.json` exists, it takes precedence. Otherwise, `codex-hooks` falls back to Claude's `settings.json`.

Example `~/.codex/hooks.json`

Create `~/.codex/hooks.json` like this:

This example only uses built-in macOS commands so it works without any custom scripts:

mkdir -p ~/.codex
cat > ~/.codex/ho