codex-cli 0.124.0 fails to start when hook config is present and codex_hooks is enabled

Resolved 💬 3 comments Opened Apr 23, 2026 by elmakus Closed Apr 23, 2026

Summary

codex-cli 0.124.0 fails to start when hook configuration is present and features.codex_hooks = true.

The CLI exits with:

Error loading config.toml: invalid type: map, expected a sequence
in `hooks`

The current docs say hooks should live in ~/.codex/hooks.json or <repo>/.codex/hooks.json, not inside config.toml:

Impact

This blocks upgrading to 0.124.0 for installations that use Codex hooks. In practice it breaks real setups that enable codex_hooks, including GSD-installed Codex hook integrations.

Reproduction

I can reproduce this on Linux with a minimal temporary CODEX_HOME.

  1. Install @openai/codex@0.124.0
  2. Create a temp config directory
  3. Write this config.toml:
[features]
codex_hooks = true
  1. Write this hooks.json next to it:
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "echo hi"
          }
        ]
      }
    ]
  }
}
  1. Run Codex against that config:
CODEX_HOME="$TMP" codex features list

Expected behavior

Codex should start and load the hook configuration, or at minimum emit a validation error that points to hooks.json if the JSON schema is wrong.

Actual behavior

Codex exits immediately with:

Error loading config.toml: invalid type: map, expected a sequence
in `hooks`

The error mentions config.toml and hooks, even though the documented hook configuration lives in hooks.json.

Additional notes

  • I also hit the same error when a legacy [[hooks]] block is present in config.toml.
  • If I disable hooks entirely with:
[features]
codex_hooks = false

then 0.124.0 starts normally.

  • This makes the regression look specific to the hook loader / hook config parsing path.

Environment

  • Codex CLI: 0.124.0
  • Install method: npm install -g @openai/codex@0.124.0
  • Node: v24.14.1
  • npm: 11.11.0
  • OS: Linux 6.17.0-22-generic x86_64

Proposed next step

Please verify whether 0.124.0 regressed hook config loading, especially the documented hooks.json path and error reporting.

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗