title: "Hooks and Commands — Codex CLI" tested_with: codex-cli: "0.2.x" last_updated: 2026-03-21 status: proven difficulty: intermediate prerequisites: [03-prompting-for-agents]

Hooks and Commands in Codex CLI

Codex CLI takes a different approach to customization than Claude Code. Where Claude Code provides a rich hooks system for attaching behavior to tool events, Codex CLI relies on its sandbox model, approval modes, and instruction configuration to shape agent behavior. Understanding these differences helps you make the right customization choices for each tool.

Configuration in Codex CLI

Codex CLI is configured through multiple layers:

  • codex.yaml — A project-level configuration file in your repository root. This defines default model, approval mode, and project-specific settings.
  • AGENTS.md — The project memory file, equivalent to Claude Code's CLAUDE.md. This is where you write behavioral instructions for the agent.
  • ~/.codex/config.yaml — User-level configuration that applies across all projects.
  • Command-line flags — Override any configuration for a single session.

A typical codex.yaml looks like this:

model: o4-mini
approval_mode: suggest
project_doc: AGENTS.md

The approval_mode setting is the most important customization lever in Codex CLI. It fundamentally changes how the agent interacts with your system.

Approval Modes as Behavioral Control

Codex CLI offers three approval modes, and choosing the right one is the primary way you customize agent behavior:

suggest mode: The agent can read files and propose changes, but every write operation and command execution requires your explicit approval. This is the most conservative mode. Use it when you are exploring a new codebase, working on sensitive code, or when you want to review every action.

auto-edit mode: The agent can read and write files without approval, but command execution (bash commands, running tests) still requires your confirmation. This is a good middle ground — the agent can edit code freely but cannot run anything that might have side effects.

full-auto mode: The agent can read, write, and execute commands without approval. Operations are sandboxed (more on this below), but within the sandbox the agent operates autonomously. Use this for well-understood tasks where you trust the agent and want maximum speed.

These modes give you coarse-grained but effective control over agent behavior. Where Claude Code uses hooks to selectively allow or block specific operations, Codex CLI uses approval modes to set the overall autonomy level and the sandbox to enforce boundaries.

The Sandbox Model

Codex CLI's most distinctive feature is its sandbox. In full-auto mode, commands run inside a sandboxed environment that restricts:

  • Network access — The agent cannot make outbound network requests by default. This prevents accidental data exfiltration, unintended API calls, and downloading of unknown code.
  • Filesystem access — The agent can only access the project directory and specific allowed paths. It cannot read or modify files outside the project.
  • Process isolation — Commands run in a contained environment that limits their blast radius.

The sandbox serves the same purpose as many Claude Code hooks — preventing dangerous operations — but it does so at the infrastructure level rather than the event-driven level. You do not need a hook to prevent rm -rf / because the sandbox will not allow it.

This is an important architectural difference. Claude Code hooks are opt-in protection: you add hooks to block specific behaviors. Codex CLI's sandbox is opt-out restriction: everything is blocked by default, and you allow specific behaviors. The sandbox model is more secure by default but less flexible for fine-grained customization.

Configuring Sandbox Permissions

You can expand the sandbox's permissions when your workflow requires it:

sandbox:
  allow_network:
    - "registry.npmjs.org"
    - "api.github.com"
  allow_paths:
    - "/tmp"
    - "~/.npm"

Be deliberate about what you allow. Each permission you add weakens the sandbox. If you find yourself allowing everything, you are better off using auto-edit mode with manual command approval instead.

Behavioral Configuration Through AGENTS.md

Since Codex CLI does not have an event-driven hooks system, your primary tool for shaping agent behavior is the AGENTS.md file. This makes the quality of your project memory instructions even more important than it is with Claude Code.

Where a Claude Code user might write a brief instruction in CLAUDE.md and back it up with a hook, a Codex CLI user needs the instruction itself to be thorough enough that the agent follows it reliably.

Effective patterns for AGENTS.md behavioral control:

## Mandatory Workflow

Before modifying any file in `src/`, ALWAYS:
1. Run `npm test` to establish a baseline
2. Make your changes
3. Run `npm test` again to verify nothing broke
4. Run `npx eslint src/` to check for lint errors

If any step fails, fix the issue before proceeding.

## Forbidden Operations

NEVER:
- Commit directly to the `main` or `master` branch
- Modify files in `migrations/` — these are immutable after creation
- Delete test files
- Run `npm publish` or any deployment command

## Required Patterns

All new functions must include:
- JSDoc comments with @param and @returns
- At least one unit test in the corresponding .test.ts file
- Error handling for invalid inputs

These instructions work well in Codex CLI because the agent's instruction-following is strong and the sandbox prevents the worst outcomes even if the agent deviates. The combination of clear instructions plus sandbox constraints gives you reasonable control without hooks.

Practical Customization Examples

Example 1: Enforcing Test-Driven Workflow

In Claude Code, you might use a PostToolUse hook to run tests after every edit. In Codex CLI, you configure this through instructions and approval mode:

AGENTS.md:

## Test-Driven Workflow

For every code change:
1. Write or identify the relevant test FIRST
2. Run the test to see it fail (or confirm existing tests pass)
3. Make the code change
4. Run the test suite to verify
5. Do not consider the task complete until all tests pass

The test command is: `npm test`

codex.yaml:

approval_mode: auto-edit

With auto-edit mode, the agent can write code freely but must get your approval before running npm test. This gives you a natural checkpoint to verify the agent is following the test-driven workflow.

Example 2: Safe Database Operations

## Database Safety

This project uses PostgreSQL. The following rules are absolute:
- NEVER run DROP, TRUNCATE, or DELETE without WHERE on any production table
- Always use transactions for multi-step database operations
- New migrations go in `db/migrations/` with the naming format: `YYYYMMDD_HHMMSS_description.sql`
- Test all SQL against the development database before suggesting changes to production configs

Combined with sandbox network restrictions, the agent cannot accidentally connect to a production database even if it ignores the instructions.

Example 3: Code Review Workflow

## Review Checklist

When asked to review code, follow this checklist:
1. Check for security issues (SQL injection, XSS, auth bypasses)
2. Check for error handling (are errors caught? are they logged?)
3. Check for test coverage (are new code paths tested?)
4. Check for naming conventions (camelCase for variables, PascalCase for types)
5. Check for documentation (public APIs must have JSDoc)
6. Summarize findings as a numbered list with severity (critical/warning/info)

This achieves through instructions what Claude Code might achieve through a custom slash command. The result is the same — a standardized review process — but the mechanism is different.

Where Codex CLI Customization Is More Limited

Honest assessment of the gaps:

No event-driven hooks. You cannot automatically run a command every time the agent edits a file. You rely on instructions and manual approval instead. This means behaviors that Claude Code can guarantee, Codex CLI can only strongly encourage.

No custom slash commands. There is no equivalent to Claude Code's .claude/commands/ directory. You can define workflow prompts in your AGENTS.md, but there is no shortcut invocation mechanism. Workaround: create a section in AGENTS.md called "Workflows" and reference them by name in your prompts — "Follow the Review Checklist workflow."

No post-action automation. After the agent edits a file, you cannot automatically trigger a linter, formatter, or test run. The agent must decide to do it (based on instructions) or you must approve it (based on approval mode). Workaround: use auto-edit mode and make the agent's instructions explicit about running verification commands. Then approve those commands when they come up.

No output interception. You cannot inject messages into the agent's context based on tool output. In Claude Code, a hook can analyze tool output and feed modified information back to the agent. Codex CLI does not have this capability. The agent sees raw tool output only.

Workarounds and Patterns

Despite these limitations, experienced Codex CLI users have developed effective patterns:

The pre-prompt script. Before starting a Codex CLI session, run a shell script that checks prerequisites — correct branch, clean working tree, environment variables set. This is manual but ensures the agent starts from a known-good state.

#!/bin/bash
# pre-session.sh
echo "Checking prerequisites..."
BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [ "$BRANCH" = "main" ]; then
  echo "ERROR: You are on main. Create a feature branch first."
  exit 1
fi
if ! git diff --quiet; then
  echo "WARNING: You have uncommitted changes."
fi
echo "Ready for Codex CLI session."

The verification prompt. End every task with a standard verification request: "Before you finish, run the test suite, run the linter, and confirm all checks pass." Experienced users keep this as a text snippet they paste at the end of every session.

The wrapper script. Create a shell alias or script that launches Codex CLI with your preferred settings:

#!/bin/bash
# codex-work.sh
codex --model o4-mini --approval-mode auto-edit --project-doc AGENTS.md "$@"

The post-session hook. After the Codex CLI session ends, run your verification suite manually:

#!/bin/bash
# post-session.sh
echo "Running post-session checks..."
npm test && npx eslint src/ && echo "All checks passed." || echo "ISSUES FOUND — review before committing."

These patterns are less elegant than Claude Code's integrated hooks, but they are effective and easy to understand. They follow the Unix philosophy of small, composable tools — even if the composition is manual rather than automatic.

Making the Choice

If your primary concern is automated enforcement — things must happen every time without exception — Claude Code's hooks system is better suited.

If your primary concern is security and containment — preventing the agent from doing harm — Codex CLI's sandbox model is stronger by default.

If you use both tools (many teams do), let each play to its strengths. Use Claude Code for complex, multi-step workflows where hooks ensure quality gates are met. Use Codex CLI for exploratory work where the sandbox keeps experiments contained.

Neither tool's customization system is complete. Both are evolving rapidly. The principles matter more than the specific mechanisms: define your requirements clearly, enforce the critical ones structurally, and verify the rest through review.