Core Hooks
The four built-in hooks installed by omx setup — keyword detector, ralph stop-gate, Bash safety guard, and exit-code advisor.
Core hooks are the handlers that omx setup installs for you automatically. Each one wires a specific OMX workflow skill into the matching Codex lifecycle event, with no extra configuration on your part. They stay narrow. A hook has one responsibility, and when its concern isn't in play, it does nothing at all.
Structure
All four hooks live in .codex/hooks.json and share one entrypoint, dist/scripts/codex-native-hook.js. That entrypoint reads the Codex event type and routes it to the right handler. Activation is a single flag. Set [features] codex_hooks = true in .codex/config.toml.
Plugin hooks in .omx/hooks/*.mjs extend this interface but do not replace it.
The four built-in hooks
keyword-detector (UserPromptSubmit)
Scans every user prompt for magic keyword phrases. On a match it writes skill activation state to .omx/state/ and can prepend developer context. Supports both explicit $skill invocations and implicit phrase matching with word-boundary guards. Intent guards prevent accidental triggering on ordinary prose containing words like "team" or "parallel". See Magic Keywords.
ralph stop-gate (Stop)
Checks whether a ralph, autopilot, ultrawork, or ultraqa run is still active when the model stops. If active and not yet terminal, it returns decision: "block" to keep the run going. Reads state from .omx/state/{mode}-state.json.
pre-tool-use guard (PreToolUse, Bash-only)
Cautions on destructive commands (rm -rf dist) and blocks inline git commit calls that lack the required trailer (Co-authored-by: OmX <omx@oh-my-codex.dev>).
post-tool-use advisor (PostToolUse, Bash-only)
Interprets non-zero exit codes, permission-denied errors, and missing-path messages, then injects corrective guidance into the next prompt context.
Checking hook status
Verify that hooks are installed correctly:
omx doctorInspect hook state directly after a keyword fires:
cat .omx/state/skill-active-state.json