Codex: Codex Rules & Hooks
Last updated: 2026-08-31
AGENTS.md and the hooks mechanism let you precisely control Codex's behavior in your project — what it can do, what it can't, and what rules to follow.
📋 Prerequisites: Understanding Codex basic configuration
1. What You Will Learn
- AGENTS.md rules file in detail
- Hooks mechanism
- Rule priority
- Practical configuration
2. AGENTS.md In Detail
AGENTS.md is a rules file in the project root that Codex automatically reads on startup as persistent context.
(1) Basic Structure
MARKDOWN
# AGENTS.md
## Project Overview
Project Name: E-Commerce API
Tech Stack: FastAPI + PostgreSQL + Redis
Code Standards: PEP 8 + Black formatter
## Code Rules
- All functions must have type annotations
- All API endpoints must have input validation
- Use dependency injection
- Use custom exception classes for error handling
## File Structure
- src/api/ - API routes
- src/models/ - Data models
- src/services/ - Business logic
- src/tests/ - Test files
## Prohibited Operations
- Do not modify .env files
- Do not delete existing tests
- Do not install new dependencies (requires human confirmation)
- Do not modify existing migrations in database/migrations/
(2) Rule Types
| Type | Description | Example |
|---|---|---|
| Code Style | Coding conventions | "Use TypeScript strict mode" |
| Architecture Constraints | Design limitations | "All APIs must go through service layer" |
| Prohibited Operations | Things not to do | "Do not modify .env files" |
| Verification Requirements | Completion standards | "Ensure pytest passes" |
| Project Context | Background knowledge | "Project uses microservices architecture" |
▶ Example 1: Alice's AGENTS.md
MARKDOWN
# AGENTS.md
## Project Overview
Next.js 14 e-commerce site, using App Router + TypeScript + Prisma
## Code Rules
- Components use functional components + TypeScript
- Use server actions instead of API routes
- Data fetching uses RSC (React Server Components)
- Styling uses Tailwind CSS
- Forms use React Hook Form + Zod validation
## Directory Conventions
- app/ - Pages and routes
- components/ - Reusable components
- lib/ - Utility functions and configuration
- types/ - TypeScript type definitions
## Prohibited Operations
- Do not use 'use client' unless necessary
- Do not install new UI libraries (use existing shadcn/ui)
- Do not modify existing models in prisma/schema.prisma (only add new ones)
- Do not modify middleware.ts
3. Hooks Mechanism
Hooks are scripts that automatically execute when specific events are triggered.
(1) Hook Types
| Hook | Trigger | Purpose |
|---|---|---|
| pre-task | Before task execution | Prepare environment, load context |
| post-task | After task completion | Run tests, format code |
| pre-commit | Before commit | Lint check, code review |
| on-error | On error | Error report, rollback |
(2) Configure Hooks
TOML
# .codex/config.toml
[hooks]
# Auto-run tests after task completion
post-task = "npm test"
# Auto-format before commit
pre-commit = "npm run format && npm run lint"
# Send notification on error
on-error = "curl -X POST https://hooks.slack.com/xxx -d 'Codex error'"
(3) Hook Scripts
BASH
# .codex/hooks/post-task.sh
#!/bin/bash
# Run tests
npm test
if [ $? -ne 0 ]; then
echo "Tests failed! Fixing..."
codex --full-auto "Fix all failing tests"
fi
# Format code
npm run format
# Check lint
npm run lint
▶ Example 2: Bob's Automation Hooks
TOML
# Bob's hook configuration
[hooks]
post-task = "bash .codex/hooks/post-task.sh"
# .codex/hooks/post-task.sh
#!/bin/bash
npm test # Run tests
npm run lint -- --fix # Fix lint
npm run format # Format
echo "Hook: post-task completed"
4. Multi-level AGENTS.md
Codex supports multi-level AGENTS.md, effective from root to subdirectories:
TEXT
📖 Display only
project/
├── AGENTS.md # Global rules
├── src/
│ ├── AGENTS.md # src directory rules
│ ├── api/
│ │ └── AGENTS.md # API module rules
│ └── auth/
│ └── AGENTS.md # Auth module rules
(1) Priority
TEXT
📖 Display only
Subdirectory AGENTS.md > Parent directory AGENTS.md > Root AGENTS.md
(2) Practical Usage
MARKDOWN
<!-- src/api/AGENTS.md -->
# API Module Rules
- All endpoints must have Swagger documentation
- Use Pydantic for request/response validation
- Return standard response format: { data: ..., error: ... }
5. Rule Priority
TEXT
📖 Display only
AGENTS.md subdirectory > AGENTS.md root > Skills > Config files > Default behavior
❓ FAQ
Q Must AGENTS.md be in the project root?
A Root AGENTS.md is required; subdirectory AGENTS.md is optional. Codex automatically reads all AGENTS.md files from the current working directory and its parents.
Q Can hooks be skipped?
A Yes. Launch Codex with
--no-hooks to skip all hooks.Q Does AGENTS.md consume context window?
A Yes, but very little. Codex compresses AGENTS.md content to reduce token consumption.
Q What if a hook script errors?
A Hook errors don't affect Codex's main task. Codex logs the error and continues execution.
Q Can different rules be set for different file types?
A Yes. Define rules by file type or directory in AGENTS.md. Codex matches the corresponding rules based on the files being operated on.
📖 Summary
- AGENTS.md is a project-level rules file, Codex reads it automatically
- Rule types: code style, architecture constraints, prohibited operations, verification requirements
- Hooks: pre-task / post-task / pre-commit / on-error
- Multi-level AGENTS.md: subdirectory > parent > root
- Rule priority: AGENTS.md > Skills > Config > Defaults
📝 Exercises
- Basic (⭐): Create an AGENTS.md for your project, defining code style and prohibited operations.
- Intermediate (⭐⭐): Configure a post-task hook for automatic testing and formatting after task completion.
- Advanced (⭐⭐⭐): Design a multi-level AGENTS.md scheme — global rules at root + module-specific rules in each directory.
