Codex-Native Hooks
How OMX uses the Codex CLI native hook interface directly, and the boundary between native coverage and runtime fallback.
Codex CLI reads hook registrations from the plugin hook surface or from .codex/hooks.json, depending on the install path. Current setup-owned fallback config enables [features].hooks = true and [features].goals = true; legacy codex_hooks remains only as a migration alias. Plugin installs that support official plugin-scoped hooks use [features].plugin_hooks = true.
Installation structure
For plugin installs on Codex versions with plugin-scoped hook support, the packaged plugin owns hook registration:
plugins/oh-my-codex/.codex-plugin/plugin.jsonpoints Codex at./hooks/hooks.jsonplugins/oh-my-codex/hooks/hooks.jsonregisters OMX lifecycle hook commands with${PLUGIN_ROOT}.codex/config.tomlenables[features].plugin_hooks = trueand[features].goals = true
omx setup still owns fallback native Codex artifacts for legacy installs and older Codex versions:
.codex/config.toml— enables[features].hooks = true(or legacy[features].codex_hooks = trueonly when that is the available feature) plus[features].goals = true.codex/hooks.json— registers the OMX handlerdist/scripts/codex-native-hook.js
User-managed hook entries already present in .codex/hooks.json are preserved during installation. omx uninstall removes only the OMX-managed entries and leaves user hooks in place.
The shell wrapper around the Codex binary is still supported via omx tmux-hook, but it is not the primary path for native events.
Coverage matrix
| OMX concern | Codex event | Status |
|---|---|---|
| Session bookkeeping, wiki startup context | SessionStart | Native |
| Keyword detection, skill state seeding | UserPromptSubmit | Native |
| Bash safety checks, commit format guard, document-refresh warnings | PreToolUse | Native-partial |
| Command-not-found guidance, exit-code review | PostToolUse (Bash only) | Native-partial |
| Ralph / autopilot / ultrawork / ultraqa continuation | Stop | Native-partial |
| Auto-nudge on stalled turns | Stop | Native-partial |
Session-end wiki capture, session-idle | — | Runtime-fallback |
| Non-Bash tool interception when Codex supplies tool events | PreToolUse / PostToolUse | Native-partial |
"Native-partial" means the native path handles the common case; edge cases fall back to the notify-hook or tmux runtime path.
How to verify
Check that hooks are installed correctly:
omx doctorSmoke test that the native hook path executes end-to-end:
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"Plugin dispatch logs are written to .omx/logs/hooks-YYYY-MM-DD.jsonl.
Codex CLI PreToolUse stdout currently accepts systemMessage; internal hook fields are stripped before stdout. Native hooks also treat null output as success, and Windows native hook launch avoids shell wrapping.