Cmd. /hooks

Purpose

Review lifecycle hooks and manage trust or disabled state.

/hooks

Availability

The installed command menu and account or organization settings determine availability.

Examples

/hooks

When to use it

1. Run /hooks after adding .codex/hooks.json or inline [hooks] config to verify source and trust state.
2. Before enabling plugin-bundled hooks, check /plugins for plugin state and /hooks for actual hook behavior.
3. Record which hooks are managed by policy and which are local project hooks.

Choosing related commands

Where hooks live

Hooks from every matching source run, and matching command hooks for the same event start concurrently. One hook cannot stop another from starting.

Minimal configuration

This .codex/hooks.json routes shell commands through a policy script before they run.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/check_command.py\"",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

In config.toml, write the matcher group as [[hooks.PreToolUse]] and each handler as [[hooks.PreToolUse.hooks]]. After saving, review and trust the hook in /hooks before it runs.

Hook events

PreToolUse covers shell commands, apply_patch file edits, MCP tool calls, and other local function tools. Hosted tools such as WebSearch are not covered.

Input and output

• Each hook receives one JSON object on stdin. Common fields are session_id, transcript_path, cwd, hook_event_name, and model; some events add tool_name, tool_input, prompt, or source.
• Exit code 0 with no output means success. For events that support blocking, exit code 2 blocks the action and uses stderr as the reason.
• Return a PreToolUse denial in hookSpecificOutput.permissionDecision and a PermissionRequest decision in hookSpecificOutput.decision.behavior (allow or deny). If any matching hook denies, the request is denied.
• matcher is a regular expression. For tool events it filters tool names such as Bash, Edit|Write, or mcp__filesystem__.*; "*" or an empty value matches everything.
• timeout is in seconds and defaults to 600. Output over about 2,500 tokens is saved to disk and the model receives a preview.

Effects and persistence

Shows configured hooks and their triggers. Editing a hook changes what runs when its event occurs.

/hooks opens the hook browser so you can inspect configured lifecycle hooks, trust new or changed hooks, and disable individual non-managed hooks before they run.

A startup warning points to /hooks when a hook needs review. Trust is tied to the hook's current hash, so a new or edited hook is skipped until you trust it again.

Cautions

Hooks are on by default. To turn them all off, set hooks = false under [features] in config.toml (codex_hooks is the older name). --dangerously-bypass-hook-trust runs enabled hooks without persisted trust for a single invocation, so keep it out of shared scripts.

• Managed hooks are trusted by policy and cannot be disabled from the user hook browser.
• Project-local hooks load only when the project .codex/ layer is trusted.
• User approval of a project hook is tied to the exact content hash; review and trust it again after a change.
• MCP hook handlers reuse an existing connection, run synchronously, cannot request approval, and do not trigger other hooks. Treat auth and availability failures as a separate failure path.
• Hooks are guardrails, but they are not a complete enforcement boundary for every shell or tool path.

Official sources

• Developer Commands
• Hooks
• Changelog

Complete command list · Verification scope · History for this command