Codex Rules and Hooks |

\\n\\n

Through Rules and Hooks, you can customize Codex’s behavior to better fit your workflow. This section details both features.

\\n\\n

---

\\n\\n

Rules

\\n\\n

Rules allow you to define custom behavioral guidelines for Codex, applied to all conversations.

\\n\\n

Rule File Locations

\\n\\n

Codex loads rules from the following locations:

\\n\\n

\\n
• ~/.codex/rules/ — User-level rules
\\n
• {project}/.codex/rules/ — Project-level rules
\\n

\\n\\n

Rule File Format

\\n\\n

## Create rule file\\n\\n# My coding rules\\n\\n## Code style\\n\\n - Use 4-space indentation\\n\\n - Maximum 100 characters per line\\n\\n - Always use const/let, never use var\\n\\n## Commenting conventions\\n\\n - Public functions must include JSDoc comments\\n\\n - Add inline comments for complex logic\\n\\n - Remove all debug console statements.log\\n\\n## Test requirements\\n\\n - All new features must include test cases\\n\\n - Test file naming:*.test.js or *.spec.js\\n\\n## Git submit\\n\\n - submitCommit messages follow Conventional Commits format\\n\\n - submitRun lint and tests before commit

\\n\\n

Enabling Rules

\\n\\n

## Enable rules in configuration\\n\\n\\n\\n codex_hooks = true

\\n\\n

\\n

Rules are injected into the system prompt of each conversation, ensuring Codex always adheres to your coding standards.

\\n

\\n\\n

---

\\n\\n

Hooks

\\n\\n

Hooks allow you to execute custom actions when specific events occur.

\\n\\n

Hook File Location

\\n\\n

Hooks are configured in ~/.codex/hooks.json:

\\n\\n

## Create hook configuration\\n\\n{\\n\\n "hooks": [\\n\\n {\\n\\n "event": "on_tool_call",\\n\\n "match": "shell",\\n\\n "action": "allow"\\n\\n },\\n\\n {\\n\\n "event": "on_task_complete",\\n\\n "action": "notify",\\n\\n "command": "echo 'Task completed'"\\n\\n }\\n\\n ]\\n\\n }

\\n\\n

Available Events

\\n\\n\\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n

Event	Description
on_tool_call	Triggered before a tool call
on_task_start	Triggered when a task starts
on_task_complete	Triggered when a task completes
on_error	Triggered when an error occurs
on_message	Triggered when a message is received

\\n\\n

Hook Actions

\\n\\n\\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n

Action	Description
allow	Allow the operation to proceed
deny	Block the operation
notify	Send a notification
log	Log the event
custom	Execute a custom script

\\n\\n

\\n

Enabling hooks requires setting .codex_hooks = true

\\n

\\n\\n

---

\\n\\n

Practical Examples

\\n\\n

Example 1: Auto-run Tests

\\n\\n

Automatically run tests after Codex modifies a file:

\\n\\n

## Automated test hook\\n\\n{\\n\\n "hooks": [\\n\\n {\\n\\n "event": "on_tool_call",\\n\\n "match": "edit_file",\\n\\n "action": "custom",\\n\\n "command": "npm test",\\n\\n "timeout": 60\\n\\n }\\n\\n ]\\n\\n }

\\n\\n

Example 2: Enforce Code Review

\\n\\n

Enforce code review before committing:

\\n\\n

## Code review hook\\n\\n{\\n\\n "hooks": [\\n\\n {\\n\\n "event": "on_tool_call",\\n\\n "match": "git_commit",\\n\\n "action": "custom",\\n\\n "command": "/review",\\n\\n "require_approval": true\\n\\n }\\n\\n ]\\n\\n }

\\n\\n

Example 3: Log Commands

\\n\\n

Log all command executions:

\\n\\n

## Logging hook\\n\\n{\\n\\n "hooks": [\\n\\n {\\n\\n "event": "on_tool_call",\\n\\n "match": "shell",\\n\\n "action": "log",\\n\\n "log_file": "/tmp/codex-commands.log"\\n\\n }\\n\\n ]\\n\\n }

\\n\\n

---

\\n\\n

Difference Between Rules and Hooks

\\n\\n\\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n \\n

Feature	Rules	Hooks
Timing	Applied at conversation start	Triggered on specific events
Primary Use	Define coding standards	Automate actions
Configuration Location	rules/ directory	hooks.json

\\n\\n

\\n

Rules and hooks can be used together: Rules define “how”, hooks define “when”.

\\n

\\n\\n

---

\\n\\n

Best Practices

\\n\\n

Rule Best Practices

\\n\\n

\\n
• Keep rules concise and clear
\\n
• Avoid overly restrictive constraints
\\n
• Adjust rules based on project needs
\\n

\\n\\n

Hook Best Practices

\\n\\n

\\n
• Avoid long-running hooks
\\n
• Set reasonable timeouts
\\n
• Test hook behavior
\\n

\\n\\n

\\n

Overusing hooks may impact Codex performance—only add hooks that are truly necessary.

\\n

\\n\\n

---

\\n\\n

Frequently Asked Questions

\\n\\n

Q: Rules are not taking effect?

\\n\\n

Ensure the rule file is in the correct location and codex_hooks is enabled.

\\n\\n

Q: If a hook fails, does it block the operation?

\\n\\n

It depends on the hook configuration—some failures may block subsequent operations.

\\n\\n

Q: Can rules be enabled/disabled dynamically?

\\n\\n

Yes—rules can be controlled via configuration files or environment variables.