Codex-Native Hooks
How OMX wires directly into Codex CLI's native hook surface instead of a shell wrapper, and which lifecycle events are covered natively versus via runtime fallback.
Codex CLI exposes a native hook surface: when [features] codex_hooks = true is set in .codex/config.toml, Codex invokes external handlers at defined lifecycle points by reading registrations from .codex/hooks.json. OMX uses this surface directly rather than wrapping the Codex binary in a shell script.
What it is
omx setup writes two files: .codex/config.toml (enabling codex_hooks) and .codex/hooks.json (registering the OMX handler command dist/scripts/codex-native-hook.js). The setup preserves any user-managed hook entries already in .codex/hooks.json. omx uninstall removes only the OMX-managed entries; user hooks stay in place. The alternative — a shell wrapper around the Codex binary — is still supported via omx tmux-hook but is not the primary path for native events.
Native vs. runtime-fallback coverage
| 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 | PreToolUse (Bash only) | 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 | — | Runtime-fallback |
"Native-partial" means the native path handles the common case; edge cases fall back to the notify-hook or tmux runtime path.
Example
Verify that native hooks are installed and shaped correctly:
omx doctorRun a smoke test to confirm 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.