Setup Hook — Runtime Atlas

Setup Hook

The new Setup hook event that can be triggered via --init, --init-only, or --maintenance CLI flags.

A Setup hook is a ~/.claude/settings.json event that fires before session initialization via --init, --init-only, or --maintenance CLI flags, receiving session context and trigger intent as JSON input.

How It Works

Setup hooks execute before Claude Code's main session begins, triggered by explicit CLI flags. The hook receives context as JSON including session_id, cwd, transcript_path, and trigger (either "init" or "maintenance"). Two triggers behave differently: --init and --maintenance start a full session after the hook completes, while --init-only runs the hook and exits immediately. This makes --init-only ideal for CI/CD pipelines and cron jobs that need bootstrapping work without interactive sessions.

What the Test Found

A 2026-01-16 runtime test configured a Setup hook in settings.json pointing to a bash script. All three CLI paths succeeded:

--init fired the hook with "trigger": "init" and started a session
--init-only fired the same hook, then exited (no session, no prompt required)
--maintenance fired the hook with "trigger": "maintenance" and started a session

The hook received complete context: session ID, working directory, transcript path, and hook event name. No failed attempts; all paths worked on first fire.

Why It Matters

Setup hooks enable automated setup without session overhead. A CI system can call claude --init-only with a hook that preps dependencies, seals environment variables, or logs bootstrap events—then exit cleanly. Unlike general-purpose hooks that fire during a session, Setup hooks run in the pre-session window where the tool is still initializing, making them safe for lightweight infrastructure work.

Caveats

These flags (--init, --init-only, --maintenance) work in version 2.1.10 but do not appear in claude --help output. Distinguishing intent via the trigger field is reliable—--init and --init-only both set "trigger": "init" rather than separate values—so hook logic must infer from context if finer differentiation is needed.

Evidence & receipt

file2.1.10/tests/01-setup-hook/TEST-RESULTS.md

◇ ed25519 receipt

idprimitive_3f2a26d1519c3632bb26eba4

alged25519

pubkey9b87705613b1e2fd064d57fa75a6b679d2856ceafad6b1daa8f982493871b6dd

sig

b0a3f761adb6c5408944f9557d8ba6c9d4607e1e4645239bc12d3c6d3ba63f2ff84096da36d537ee790ff5888f1f37a00564744079249ee0941cb5d382dd5606

Signed with an ed25519 key held off the repo. Anyone can verify against the published public key; nobody without the secret key can forge it. Click verify: it recomputes the signature in your browser. The signature proves integrity and authorship of this exact content — not a third-party timestamp or that the underlying claim is objectively true. signedAt is when the @f3/attest pipeline ran, not when the work happened; the evidence refs carry the source dates.

Connected

instance-of Event Interposition Class
introduces (in) 2.1.10 (2.1.10) Release
verifies (in) Setup Hook — runtime test Test

Setup Hook

Primitive

Kind	Primitive
Introduced	Claude Code 2.1.10
Class	Event Interposition
Epistemic	tested · runtime-test
Evidence	1 ref
Receipt	ed25519 · verifiable

Hands-on runtime test · Claude Code 2.1.10

Cite this page

Hunter, R. "Setup Hook." The Runtime Atlas. Content-addressed entity primitive_3f2a26d1519c3632bb26eba4, ed25519-signed (integrity, not third-party timestamp). https://ryanhunter.io/atlas/e/2-1-10-setup-hook

@misc{atlas-2-1-10-setup-hook,
  title  = {Setup Hook},
  author = {Hunter, Ryan},
  note   = {The Runtime Atlas; entity primitive_3f2a26d1519c3632bb26eba4; ed25519-signed for integrity},
  url    = {https://ryanhunter.io/atlas/e/2-1-10-setup-hook}
}