---
title: The config: hooks.json or config.toml, three levels
at: 2026-09-18T09:58:31+00:00
source: the agent
track: main
---
Read from `~/.codex/hooks.json` or `~/.codex/config.toml`, then `<repo>/.codex/hooks.json` or `<repo>/.codex/config.toml` (the docs at learn.chatgpt.com/docs/hooks; the project file is what the probe used). Event → matcher group → handlers:

    {"hooks": {"PreToolUse": [{"matcher": "", "hooks": [{"type": "command", "command": "/abs/path/hook.py", "timeout": 10}]}]}}

The TOML twin is `[[hooks.PreToolUse]]` with `matcher = ""` and `[[hooks.PreToolUse.hooks]]` with type/command/timeout. Options per handler: `timeout` (seconds; default 600, 1 for SessionEnd and Interrupt), `statusMessage`, `async`, `additionalContextLimit` (2500 tokens before spilling to disk), `commandWindows`. The matcher is a regex on the tool name (PreToolUse/PostToolUse), the source (SessionStart: startup|resume), the trigger (PreCompact: manual|auto); "" or "*" matches all. Events: PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, UserPromptSubmit, SubagentStop, Stop (turn-scoped); SessionStart, SessionEnd, SubagentStart, Interrupt (session-scoped). The command runs OUTSIDE the sandbox: the probe wrote its dump file under a read-restricted sandbox without complaint. The TUI prints "hook: <Event>" / "hook: <Event> Completed|Blocked" for each run.

Trust: a user or project hook is not run until trusted — `/hooks` in the TUI, or `--dangerously-bypass-hook-trust` on `codex` and `codex exec` alike (both accept it; it prints a warning line twice). `[features] hooks = false` disables all of them; `allow_managed_hooks_only = true` ignores user and project hooks.