A cchook-compatible hook tool for Codex CLI, written in Rust.

codex-hook replaces complex JSON hook configurations with clean YAML syntax, template-based data access, and conditional logic.

cargo install --git https://github.com/syou6162/codex-hook

Codex CLI hooks require a feature flag. Add the following to ~/.codex/config.toml:

[features]
codex_hooks = true

Then register codex-hook as a command hook. You can use either inline TOML or a separate hooks.json file.

[features]
codex_hooks = true

[[hooks.PreToolUse]]
matcher = ""

[[hooks.PreToolUse.hooks]]
type = "command"
command = "codex-hook --event PreToolUse"

[[hooks.PostToolUse]]
matcher = ""

[[hooks.PostToolUse.hooks]]
type = "command"
command = "codex-hook --event PostToolUse"

Create ~/.codex/hooks.json (keep the feature flag in config.toml):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "codex-hook --event PreToolUse"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "codex-hook --event PostToolUse"
          }
        ]
      }
    ]
  }
}

Note: Do not use both hooks.json and inline [hooks] in the same config layer — Codex will merge them but emit a warning.

You can also place project-scoped hooks in .codex/config.toml or .codex/hooks.json at the project root.

Create ~/.config/codex-hook/config.yaml with your hooks:

# Block write operations to .env files
PreToolUse:
  - matcher: "Write|Edit"
    conditions:
      - type: file_extension
        value: ".env"
    actions:
      - type: output
        message: ".env files should not be modified directly"
        exit_status: 2

# Auto-format Go files after Write/Edit
PostToolUse:
  - matcher: "Write|Edit"
    conditions:
      - type: file_extension
        value: ".go"
    actions:
      - type: command
        command: "gofmt -w {.tool_input.file_path}"

codex-hook is invoked automatically by Codex CLI via the hooks configuration above. Codex passes JSON on stdin and codex-hook returns JSON on stdout.

codex-hook --event <EventType> [--config <path>]

If --config is omitted, codex-hook looks for $XDG_CONFIG_HOME/codex-hook/config.yaml, falling back to ~/.config/codex-hook/config.yaml.

The configuration file uses YAML format, compatible with cchook.

Top-level keys are PascalCase event types. Each event contains a list of hooks with matcher, conditions, and actions.

PreToolUse:
  - matcher: "Write|Edit"       # regex pattern to match tool_name
    conditions:                  # all conditions must be true (AND)
      - type: file_extension
        value: ".rs"
    actions:
      - type: output
        message: "Rust file detected"

The matcher field is a regular expression that filters hooks by tool name. It is automatically anchored (^(?:...)$) to match the full name. Use | for alternation (e.g. "Write|Edit"). An empty matcher matches everything.

All conditions in a hook must evaluate to true (AND semantics) for actions to execute. Each condition has a type and a value.

Each hook can have multiple actions. Two types are supported:

Executes a shell command via sh -c. The command's stdout is suppressed to avoid interfering with the Codex JSON protocol. stderr is inherited.

actions:
  - type: command
    command: "echo {.tool_name} >> /tmp/hook.log"

Outputs a JSON message ({"message": "..."}) to stdout. Optionally sets an exit status (non-zero takes precedence across multiple output actions).

actions:
  - type: output
    message: "Operation blocked"
    exit_status: 2

Action command and message fields support {<jq_query>} template syntax. The content inside braces is evaluated as a jq query against the JSON input from Codex.

Examples:

Empty braces {} are not treated as templates.

PreToolUse:
  - matcher: "Bash"
    conditions:
      - type: command_starts_with
        value: "rm -rf"
    actions:
      - type: output
        message: "rm -rf is not allowed"
        exit_status: 2

PostToolUse:
  - matcher: "Write|Edit"
    conditions:
      - type: file_exists
        value: ".pre-commit-config.yaml"
    actions:
      - type: command
        command: "pre-commit run --files {.tool_input.file_path}"

PreToolUse:
  - matcher: "Write|Edit"
    conditions:
      - type: cwd_contains
        value: "/my-project"
      - type: file_extension
        value: ".py"
    actions:
      - type: output
        message: "Python file in my-project — remember to run tests"

MIT