Skip to main content

require-valid-hook-structure

Require Codex hooks to follow the event, matcher-group, and handler structure.

Rule catalog ID: R025

Targeted pattern scope​

  • **/.codex/hooks.json
  • inline [hooks] tables in **/.codex/config.toml

What this rule reports​

  • {{eventName}} matcher group {{groupIndex}} handler {{handlerIndex}} must be an object.
  • {{eventName}} matcher group {{groupIndex}} must contain a non-empty hooks handler array.
  • {{eventName}} matcher group {{groupIndex}} must be an object.
  • Hook event {{eventName}} must contain a non-empty matcher-group array.
  • {{eventName}} matcher group {{groupIndex}} command handler {{handlerIndex}} must declare a non-empty command.
  • Codex hook configuration must declare a top-level hooks object.

Why this rule exists​

Require Codex hooks to follow the event, matcher-group, and handler structure.

❌ Incorrect​

A file in the targeted scope that produces any diagnostic listed above is incorrect for this rule.

✅ Correct​

A file is correct when it uses the documented Codex structure and produces no diagnostic from this rule.

Behavior and migration notes​

Included in:

  • codex.configs.minimal
  • codex.configs.recommended
  • codex.configs.strict
  • codex.configs.all

ESLint flat config example​

The preset layers supply the correct Markdown, TOML, or JSON language configuration. Override the rule only in a later matching flat-config entry:

import codex from "@typpi/eslint-plugin-codex";

export default [
 ...codex.configs.recommended,
 {
  rules: { "codex/require-valid-hook-structure": "error" },
 },
];

Further reading​