# Setup Hook

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

**Field:** Artificial Intelligence  
**Category:** Claude Code  
**Also known as:** Setup

## Think of it like

It is like you set up a tent once. You do it before the camp starts.

## Definition

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.

## Example code

```json
{
  "hooks": {
    "Setup": [
      { "matcher": "init", "hooks": [{ "type": "command", "command": "npm ci" }] }
    ]
  }
}
```

Install packages on an init run only.

## Why it matters

It keeps slow, one-off setup out of the hooks that run every session.

## Common mistake

Expecting it to run when you just type claude. It only runs with those flags.

## Three principles

- **Only with flags.** --init and more.
- **Two kinds.** init, maintenance.
- **Cannot block.** Runs and moves on.

## Related terms

- [--init Flag](https://learn.benibix.com/term/ai/init-flag)
- [SessionStart Hook](https://learn.benibix.com/term/ai/sessionstart-hook)
- [Non-Interactive Mode](https://learn.benibix.com/term/ai/non-interactive-mode)

## Told apart from

- [Setup Hook vs SessionStart Hook](https://learn.benibix.com/compare/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.

---

Source: https://learn.benibix.com/term/ai/setup-hook
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-16
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
