Fix: [features].codex_hooks is deprecated in Codex CLI

The [features].codex_hooks warning means the old config key was renamed. One-line fix, plus a workaround for the v0.130.0 warning-persistence bug that fires even after the rename.

Pallavi Joshi · June 11, 2026

If you recently upgraded Codex CLI and your terminal is showing:

[features].codex_hooks is deprecated. Use [features].hooks instead.
Enable it with --enable hooks or [features].hooks in config.toml.

You have an old config key. The fix is one line.

Why the warning appears

When Codex CLI’s hook system was in early access, the config key was [features].codex_hooks. It was a feature flag for what was still experimental behavior. When hooks reached general availability on May 14, 2026, the key was renamed to [features].hooks. The old name still works as a deprecated alias, which is why hooks were firing for you, but the runtime now logs the warning on every invocation.

Source: the Codex CLI config reference documents codex_hooks as a deprecated alias for hooks.

The fix

Open your config.toml. It lives at ~/.codex/config.toml by default.

Find the [features] section. It looks like this:

[features]
codex_hooks = true

Rename the key:

[features]
hooks = true

That is the entire change. Restart Codex CLI and the warning is gone.

If you do not have a [features] section

Hooks are enabled by default in post-GA versions. If your config.toml has no [features] section at all, there is nothing to migrate. The warning appearing without a [features] block present is the v0.130.0 bug described in the next section. If your config has a [features] block with only codex_hooks = true, delete the entire block if you want the default behavior, or keep the block with hooks = true for an explicit opt-in.

The v0.130.0 warning-persistence bug

There is a known bug in Codex CLI v0.130.0 (tracked in openai/codex#22148): the deprecation warning fires even when [features].hooks = true is already present in your config. The reporter’s exact warning text matches the one above, and the issue remains open as of this writing.

The workaround is to confirm that Codex is loading the config file you think it is. Codex CLI loads config in this order:

  1. The file at --config <path> if passed on the command line
  2. ~/.codex/config.toml
  3. Built-in defaults

If you have multiple config files on disk and the renamed key is in a file that is not being loaded, the warning persists. Run codex --show-config to print the resolved config and verify hooks = true appears in the output.

The warning is cosmetic in the sense that hooks still fire. But confirming the right config is loaded is worth doing regardless, because a silently wrong config file can cause other unexpected behavior in longer sessions.

Complete before and after

Before:

[features]
codex_hooks = true

After:

[features]
hooks = true

If your [features] block contained only codex_hooks = true, the after state can also be an absent [features] block. Hooks default to enabled.

What hooks do

Hooks are the integration surface that lets external tools observe and respond to Codex’s tool calls without being part of the agent loop. PostToolUse is the hook that fires after apply_patch and shell invocations. For a full walkthrough of the payload shape, the apply_patch parser, and the hookSpecificOutput.additionalContext channel, see Inside Codex CLI PostToolUse: what fires on apply_patch.

The hook-based testing model uses these same hooks to run tests at the point where Codex edits files, rather than at turn end only. The Codex-specific wiring is in tailtest-codex; the hooks work with any external consumer once the config key is correct.

FAQ

What is the correct config key after the rename?

[features].hooks. The old key [features].codex_hooks still works but logs the deprecation warning on every run. Rename it to silence the warning.

Hooks stopped firing after I removed the [features] block. What happened?

Hooks default to enabled, so removing the block should not disable them. Check codex --show-config to confirm the resolved value. If another config file on disk has [features].hooks = false, that file may be taking precedence.

I renamed the key and the warning is still there. What do I do?

This is the v0.130.0 bug in openai/codex#22148. Run codex --show-config to confirm Codex is reading the right file. If the resolved config shows hooks = true and the warning still appears, the bug affects your version and the warning is cosmetic. A fix is tracked in the upstream issue.

How do I use hooks for automated testing?

The tailtest Codex integration wires the PostToolUse and Stop hooks to run a per-edit test cycle against your repository’s test suite. The installer is uvx tailtest install --agent codex. No SaaS account required.