A hook is not a better prompt. It is a lifecycle checkpoint. Use it when the behavior should happen whether or not the model remembers.
Use session start for setup and binding, user prompt submit for pre-submit routing, context, and safety, and stop hooks for final gates. Keep skills, imps, CLI helpers, and manual prompts for jobs that need optional invocation, model judgment, or task-specific context.
If you want things to happen automatically, that's not what skills are for. If you want them to happen automatically, that's what hooks are for.
โ John Lindquist
Put Setup At Session Start
Session start is the setup moment. Use it for identifiers and state that later tooling needs to find without scraping the screen or asking the model to remember.
At session start, a project might record:
- session id
- working directory
- transcript location, when available
- branch name
- visible workspace surface
- a searchable session name or tag
Keep this setup boring and reliable. If later shortcuts, dashboards, or review tools need to find the right conversation, this is where the lookup trail starts.
That's the key piece of information, is that session start, like, a place to set things up.
โ John Lindquist
Route Before The Prompt Leaves
User prompt submit is the pre-submit moment. Use it when a project-specific prompt pattern should trigger local work before the model spends a turn.
Prompt submit triggers can do things like:
#testloads files tagged for test context#apiloads route and schema context!ticketcreates a tracking issue from the prompt body!summarysends the current thread to a summarizer- sensitive release terms trigger a confirmation check
Choose syntax that fits the project and team. Do not assume custom symbols will remain collision-free forever.
Use Stop Hooks As Final Gates
Stop hooks are for final checks near the end of a turn, so missing proof is surfaced before the work is treated as done.
Good stop-gate candidates:
- run the smallest relevant test
- run a formatter or linter
- check for unresolved uncertainty language
- verify an issue or summary was created
- check whether a forbidden file changed
- surface missing proof and report blocked only when the current hook behavior supports that flow
Do not claim a hook guarantees correctness. A hook can run final checks and surface missing proof; exact blocking, continuation, mutation, and appended-context behavior must be verified against the current docs and installed tool. The verification still has to be well designed.
Keep Hooks Out Of Jobs That Need Judgment
Hooks are best for mechanical behavior. If the action needs fresh reasoning each time, a hook is probably the wrong surface.
Use a hook when:
- the trigger is predictable
- the action should run automatically
- the behavior can be reviewed and trusted
- the result should not depend on the model remembering a rule
Use another surface when:
- the action is optional
- the model needs to decide whether it applies
- the work needs a large body of task-specific context
- a normal prompt, skill, CLI helper, or narrow imp would be clearer
Use Documented Events
Verify the current Codex hook docs before relying on exact event lists or payload behavior. Treat event names as current-tool details, not the durable lesson. A hook workflow should name the lifecycle moment, state what it automates, and keep examples easy to recheck.
Only some events may honor matchers, and handler support can change. Keep implementation examples conceptual until the exact matcher behavior, payload shape, return behavior, and trust flow have been checked against current docs.
That matters for shared examples: start with the workflow shape, then attach exact event names only after checking the installed tool and current docs.
Copyable Artifact: Hook Decision Checklist
Use a SessionStart hook when:
- the session needs setup before the first prompt
- you need to bind session id, cwd, transcript, branch, or visible workspace state
- later tools need to find this session without screen scraping
Use a UserPromptSubmit hook when:
- a prompt pattern should trigger local context loading
- a project shortcut should route work before the model spends a turn
- a safety check should confirm or block a risky prompt
Use a Stop hook when:
- a final check should run before the work is treated as done
- missing proof should be surfaced or reported according to verified hook behavior
- final output needs proof
Do not use a hook when:
- the behavior needs model judgment every time
- the action is optional
- the implementation is not reviewed or trusted
- a normal prompt, skill, CLI helper, or narrow imp is clearer
Implementation Notes To Verify
Before sharing executable hook examples, verify:
- exact payload fields
- whether the example blocks, continues, appends context, or only reports
- timeout behavior
- trust-review behavior
- event matcher behavior
- current docs for the installed Codex version
Concepts are portable. Hook code is version-sensitive.