Why Your Codex Hook Isn't Running: Check These Four Things First

You add a hook to Codex, start a session, and nothing seems to happen. It's easy to assume the hook is broken. In my setup, the problem wasn’t the hook itself. It was a setup detail I'd missed, and each one takes about a minute to check.

This post walks through the four checks I wish I'd run first, using a real throwaway project on Codex v0.147.0.

The setup

I created a test repository with one Python file and a project-level hook:

codex-hook-test/
├── .git/
├── ok.py
└── .codex/
├── hooks.json
└── hooks/
└── check-python.py

hooks.json registers a PostToolUse hook for file edits. The matcher is Edit|Write, and the command runs a Python script:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python .codex/hooks/check-python.py",
            "statusMessage": "Checking Python syntax",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

After creating the files, I listed the .codex folder and checked git status. Both files were there, and .codex/ showed as untracked, which is expected before the first commit.

Check 1: Did Codex load the hook?

Start Codex in the project folder and type /hooks. The panel groups hooks by event and shows two counts: Installed and Active.

In my session, the PostToolUse row showed Installed 1 and Active 1. That means Codex found the hook in the project's .codex folder and registered it.

If PostToolUse shows 0 installed, either the file isn't where Codex expects it or the JSON is invalid. Check the path first, then paste the file into a JSON validator.

Check 2: Where did you launch Codex?

Project hooks load from the project's .codex folder, so Codex has to start inside that project. The directory: line in the startup box shows where it's running.

This was my first mistake. The startup box showed directory: ~, meaning Codex was running from my home folder and wasn't looking at the project at all. Starting it from inside the project fixed it, and the box then showed directory: ~\codex-hook-test.

Run codex from the project folder, and confirm the directory: line before you debug anything else.

Check 3: Is the project a git repo?

The hook script uses git ls-files to find changed Python files. Outside a git repository, that command fails, so the hook has nothing to check.

In my first attempt, git status returned fatal: not a git repository. Confirm the folder is a repo before you start Codex:

cd C:\path\to\your-project
git status

You should see On branch followed by a list of changes or "nothing to commit." If you get fatal: not a git repository, run git init and make an initial commit.

Check 4: Does the hook command work on its own?

Before you rely on Codex to run the hook, run the script yourself from the project folder:

python .codex\hooks\check-python.py
echo "exit=$LASTEXITCODE"

On a clean repo, it should print nothing and exit with 0. If it fails here, it will fail inside Codex too, so fix the script first.

The script returns exit code 0 when every changed Python file compiles. When one doesn't, it returns exit code 2 and writes the error to stderr. To reproduce both cases, add a broken .py file to a throwaway repo and run the script again.

What "Active" does and doesn't prove

The /hooks panel tells you that Codex loaded the hook and will run it. It doesn't tell you what happens when the hook fires.

The Codex hooks documentation says a PostToolUse hook that exits with code 2 sends its feedback to the model. I haven't yet observed that in this setup, so this post doesn't claim it. The next step is a deliberate edit that should fail the check, followed by a look at what Codex does with the result.

Trust after changes

Codex requires you to review and trust non-managed hooks before they run. If you change a hook's command, Codex treats it as new and skips it until you trust it again. If a hook stops firing after an edit, open /hooks first.

Summary

If a Codex hook seems to do nothing, check these in order:

1. Did Codex load it? Open /hooks and look at Installed and Active.
2. Did you start Codex in the right folder? Check the directory: line.
3. Is the project a git repo? Needed if your hook uses git.
4. Does the command work on its own? Run it from the project folder.
5. Did you trust the hook after your last change? Re-review it in /hooks if you edited it.

Most failures come from one of those five.