Automate lifecycle work with hooks

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.

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:

  • #test loads files tagged for test context
  • #api loads route and schema context
  • !ticket creates a tracking issue from the prompt body
  • !summary sends 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.

Source references