Codex Rules and Hooks

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

Rules

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

Rule file location

Codex loads rules from the following locations:

~/.codex/rules/- User-level rules
{项目}/.codex/rules/- Project-level rules

Rule file format

Create rule file

# My Coding Rules

## Code Style
- Use 4 spaces for indentation
- Maximum 100 characters per line
- Always use const/let, not var

## Comment Conventions
- Public functions must include JSDoc comments
- Add inline comments to explain complex logic
- Remove all console.log for debugging

## Testing Requirements
- All new features must include test cases
- Test file naming: *.test.js or *.spec.js

## Git Commit
- Commit messages use Conventional Commits format
- Run lint and tests before committing

Enable Rules

Enable rules in configuration

[features]
codex_hooks = true

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

Hooks

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

Hook file location

Hooks are~/.codex/hooks.jsonconfigured in:

Create hook configuration

{
"hooks": [
{
"event": "on_tool_call",
"match": "shell",
"action": "allow"
},
{
"event": "on_task_complete",
"action": "notify",
"command": "echo 'Task completed'"
}
]
}

Available Events

Events	Description
`on_tool_call`	Trigger before tool invocation
`on_task_start`	Trigger at task start
`on_task_complete`	Trigger at task completion
`on_error`	Trigger on error
`on_message`	Trigger on message received

Hook Actions

Operation	Description
`allow`	Allow operation to continue
`deny`	Block Actions
`notify`	Send Notifications
`log`	Record Logs
`custom`	Execute custom script

Enabling hook functionality requires configuration[features].codex_hooks = true

Practical Examples

Example 1: Automatically run tests

Automatically run tests each time Codex modifies a file:

Automated test hook

{
"hooks": [
{
"event": "on_tool_call",
"match": "edit_file",
"action": "custom",
"command": "npm test",
"timeout": 60
}
]
}

Example 2: Enforce code review

Enforce code review before commit:

Code review hook

{
"hooks": [
{
"event": "on_tool_call",
"match": "git_commit",
"action": "custom",
"command": "/review",
"require_approval": true
}
]
}

Example 3: Logging

Log all command executions:

Log Hook

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

Difference between rules and hooks

Features	Rules	Hook
Timing	When conversation starts	When event is triggered
Main purpose	Define coding standards	Automation Actions
Configuration Location	rules/ directory	hooks.json

Rules and Hooks can be used together: Rules define the "how," and Hooks define the "when."

Best Practices

Rule best practices

Keep rules concise and clear
Avoid overly strict restrictions
Adjust rules according to project requirements

Hook best practices

Avoid long-running hooks
Set a reasonable timeout
Test hook behavior

Overusing Hooks may impact Codex's performance, so only add Hooks you really need.

FAQ

Q: Rules not taking effect?

Ensure the rules file is in the correct location and is enabled.codex_hooksFeatures.

Q: Will a failed Hook execution block the operation?

It depends on the Hook configuration; certain Hook failures will block subsequent operations.

Q: Can rules be dynamically enabled/disabled?

Yes, you can control them through configuration files or environment variables.

other extensions