Skip to content
BENIBIX Learn

Setup Hook vs SessionStart Hook

People think a Setup hook runs each time Claude Code starts. It does not. It runs only when you ask for it with --init-only, --init or --maintenance. SessionStart is the one that runs on every start, resume and clear. Put one-time installs in Setup, and quick context in SessionStart.

AI⌨️ Claude Code

Setup Hook

An event that fires only on a set-up run.

Setup is the hook event that fires only on a set-up run. That is a start with --init-only, or a -p run with --init or --maintenance. It never fires on a normal start. The matcher is init or maintenance. Use it for one-time jobs, such as installing packages in CI. Keep those apart from the hooks that run each session.

Example
Lucy's CI job runs claude --init-only before the real work. Her Setup hook installs the packages once.
Why it matters
It keeps slow, one-off setup out of the hooks that run every session.
Full entry
AI⌨️ Claude Code

SessionStart Hook

The event when a session starts. It can load notes for Claude.

SessionStart is the hook event that fires when Claude Code starts a new session or resumes one. The matcher says how it began: startup, resume, clear, compact or fork. Text the hook prints is added to Claude's context, so it is the place to load today's issues or recent changes. Only command and MCP tool hooks run here.

Example
Jack's SessionStart hook prints the last five commits. Claude starts each session knowing what changed.
Why it matters
Facts that change each day do not belong in CLAUDE.md. This hook fetches them fresh each time.
Full entry

In one line

Setup Hook
An event that fires only on a set-up run.
SessionStart Hook
The event when a session starts. It can load notes for Claude.