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
💡 Likely answer: A maintainer (eternal-openai, contributor) responded on this thread — see the highlighted reply below.

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 ↗

3 Comments

zyz23333 · 4 months ago

Same issue to me.Both on CLI and Windows app.

eternal-openai contributor · 4 months ago

Problem is GSD's as far as I can tell:

  • I could not repro using just the "Reproduction" steps
  • however the hint was the [[hooks]] message. Apparently, GSD used to insert this into our config, though it's not a standard config format for us. It just happened to not be marked as invalid before
  • what changed? We actually do support hooks in toml now, in addition to json (though the docs update isn't live yet). So that's what caused the conflict with GSD's "augmentation" of our config. The following works
[[hooks.SessionStart]]
matcher = "startup|resume"

[[hooks.SessionStart.hooks]]
type = "command"
command = "echo hi"

but this does not:

[[hooks]]
event = "SessionStart"
command = "echo hi"
oxysoft · 3 months ago

Indexed this hook ticket in the umbrella tracker: #21753

Goal: collect the scattered Codex hook requests and bugs into one parity matrix for Full Claude Code Hook Parity (29+), while preserving this issue as the detailed thread for its specific behavior.