Codex CLI Hooks: Setup, Boundaries, and Useful Examples

Codex CLI hooks are shell commands that run automatically at named points in a session, such as before or after the agent edits a file or before the session ends. They let you add checks, notifications, or cleanup steps without building them into every prompt. A hook runs on your machine, outside the model, so it has full access to your environment and no awareness of what the agent decided.

Tools like fenbs are a good complement to hooks for the parts hooks cannot reach: keeping the task plan, recording decisions, and passing a clear progress note to the next session after a hook-driven run finishes.

What hooks let you do

A hook fires at a lifecycle event and runs a shell command of your choosing. It cannot change what the agent decides to do next; it can only act on what has just happened or prepare what comes next. Good uses include running a test suite after a file edit, logging what changed, or sending a notification when a session ends.

Keep hooks focused on local, reversible operations. A hook that automatically deploys after every file change removes the review step that makes an automated run safe. See the guide to codex cli best practices for more on keeping automated steps inside clear boundaries.

Supported hook events

Codex CLI supports hooks for the main lifecycle points of a session. Check the OpenAI Codex repository↗ (opens in a new tab) for the current list, since the set of supported events can expand between releases. Common events include:

• After a file is written or modified by the agent.
• Before the agent executes a shell command.
• After the agent executes a shell command.
• When a session ends, whether normally or because of an error.

Each event gives your hook access to relevant context: the path of the file that changed, the command that ran, or the exit status of the session. That context arrives as environment variables or as arguments, depending on the event.

Configure hooks

Hooks live in your Codex CLI configuration file. The file is typically at ~/.codex/config.json for user-level settings or .codex/config.json in the project root for project-level ones. A project-level config applies only when you run codex from that directory.

{
  "hooks": {
    "post-file-write": "npm test -- --testPathPattern=$CODEX_FILE_PATH",
    "post-session": "echo 'Session ended' >> ~/codex-log.txt"
  }
}

The key is the event name; the value is the shell command to run. The command runs in a new shell with the session's environment variables added. You can call any script, binary, or shell one-liner.

Project-level hooks apply to everyone who runs the CLI in that directory if the config file is committed to version control. Be careful with hooks that write to shared state or send network requests: they run for every team member without asking.

Handle hook failures

A hook that exits with a non-zero code is treated as a failure. Depending on the event, a failure may stop the session or be logged and ignored. Check the Codex CLI documentation for the exact behavior per event, since some events treat hook failures as blocking and others do not.

Design hooks to fail loudly and cleanly. If a test script fails, the non-zero exit is informative; make sure the script produces output that explains why. A hook that swallows errors makes failures silent, which defeats the purpose of the check.

For steps that must not block the session, consider writing to a log file rather than exiting with an error. Review the log after the session ends rather than interrupting the agent mid-task.

Useful hook examples

• Run affected tests after each file write. Pass the changed file path to the test runner to keep the suite fast.
• Lint the changed file. A quick lint check catches syntax errors before they compound in later edits.
• Log the list of changed files to a session file. Reviewing the log afterward shows exactly what the agent touched.
• Send a desktop notification when a long session ends. Useful when you are running a full-auto task in the background.
• Snapshot the git diff before the session writes more changes. Gives you a restore point if you want to compare or revert.

The codex subagents pattern benefits from hooks too: a post-session hook on each subagent can write its result summary to a shared log, making it easy to review what each run completed before the orchestrating session continues.

What hooks cannot do

Hooks run outside the model and cannot change the agent's next decision or the content of a file it is about to write. They are side-effects of events, not interceptors. If you need to review the agent's plan before it acts, use plan mode instead of a hook.

Hooks also do not accumulate context across a session. Each invocation is a fresh shell command. For a running record of what happened during a session, write to a file from your hook or use a tool like fenbs to record task progress and lessons.

How to do this with fenbs

1. Create a free account and add the project you are running Codex CLI against.
2. Connect Codex CLI to fenbs over MCP from Integrations. Sign in with a browser.
3. At the end of each session, ask Codex CLI to save progress to fenbs: what it completed, what it checked, and the next step.
4. Add a post-session hook to your config that reminds you to review the fenbs task record before starting the next run.
5. When a hook reveals a recurring failure or a useful pattern, record it as a Lesson in fenbs so future sessions can read it before similar work.