Hook Valid Event Types
Hook event keys in .codex/hooks.json MUST use recognized Codex event type names (6 events). Unrecognized event names are silently ignored, so a typo means the hook never fires.
HighcodexstructureRules for Codex
Filtering by
Structure
5 rulesHook Handler Has Type
Each hook handler object in .codex/hooks.json MUST contain a "type" field set to command. Without a type field, Codex cannot dispatch the handler and the hook silently does nothing.
HighcodexstructureHook Command Has Field
Hook handlers with "type": "command" in .codex/hooks.json MUST include a "command" field containing the shell command to execute. Without it, Codex has no command to run and the hook fails silently.
HighcodexstructureOverride Read Order
Codex discovers instruction files in a specific order: AGENTS.override.md first, then AGENTS.md, then fallback filenames — walking from the project root to the current working directory. Document this discovery chain so users understand which file takes precedence and where to put overrides.
MediumcodexstructureSkill OpenAI YAML
Codex skill directories SHOULD contain an agents/openai.yaml file with display_name, icon, and invocation policy fields. This metadata controls how the skill appears in the Codex UI and whether it can be triggered implicitly.
LowcodexstructureEfficiency
1 ruleAGENTS.md Within Size Limit
Codex caps the combined AGENTS.md instruction chain — global ~/.codex/AGENTS.md plus every AGENTS.md from the git root down to the working directory — at 32 KiB (32,768 bytes) by default, the project_doc_max_bytes setting. Content past the cap is silently truncated and never reaches the model, with no warning. Keep the eager AGENTS.md footprint under 32 KiB, or raise project_doc_max_bytes deliberately when you need more.
Highcodexefficiency