Install Hooks

Trigger

• Keywords: install hooks, setup hooks, copy hooks, install-hooks

When NOT to Use

• Installing rules (use /install-rules)
• Installing scripts (use /install-scripts)
• Full project setup (use /project-setup)

Workflow

Phase 0: Resolve mode; obsolete-set migration (first for non-list invocations; --dry-run forwarded)
Phase 1: Locate plugin hooks dir
Phase 2: Enumerate hook scripts
Phase 3: Determine install set (--all, specific names, or interactive)
Phase 4a: Copy scripts to .claude/hooks/
Phase 4b: Merge hook definitions into settings.json
Phase 4c: Update manifest
Phase 4.5: Backfill CLAUDE.md references
Phase 5: Output report

Phase 0: Obsolete-Set Migration

Resolve the invocation mode first — Phase 0 mutates settings and deletes files, so the non-mutating modes must never reach it live: with --list, skip Phase 0 entirely (listing is read-only); with --dry-run, forward the flag so the migration also only reports:

# --list        → skip this phase
# --dry-run     → append --dry-run to the command below
node "${CLAUDE_PLUGIN_ROOT}/scripts/migrate-hook-lightweighting.js" --repo "$(git rev-parse --show-toplevel)"

Otherwise run the shared migration before any copy or merge — it is what removes the retired enforcement-layer files and their registrations (hook-lightweighting § 3.6), and running it first is what prevents the dangerous half-state (scripts-new + hooks-old).

Ordering inside the script is fixed: it deregisters settings entries first and deletes files only after the settings writes succeed; a failed settings write aborts (exit 1) before any deletion. On exit 1, stop the install and surface the report — installing on top of a repo whose deregistration failed reproduces the half-state the migration exists to prevent. Modified obsolete files are kept on disk (registration disabled) and named in the report; include those lines in Phase 5's output.

Arguments

$ARGUMENTS

Argument	Description
--all	Install all available hooks
--list	List available hooks without installing
--dry-run	Show what would be installed, no changes
--force	Overwrite existing hooks with different content
--local	Write to settings.local.json instead of settings.json
hook-names...	Specific hooks to install

Two-Layer Install

Layer	Target	Content
Scripts	.claude/hooks/*.sh	Executable hook scripts
Definitions	settings.json hooks entries	Event → script path mapping

Script dependencies: a locally installed hook resolves its helper scripts beside its own copy (.claude/scripts/…), never from the plugin. The whole dependency surface is one checker — scripts/review-state.js (which requires scripts/lib/tree-digest.js) — read by stop-guard.sh, user-prompt-review-guard.sh and post-compact-auto-loop.sh (post-skill-auto-loop.sh is deliberately zero-read: it prints one static gate-order line and consumes nothing). Missing → every hook still runs and still reminds: it reports change-class facts from live git and claims no verdict (nothing blocks — the hooks are reminders, hook-lightweighting § 3.2). Installing the checker via /install-scripts --all (or /project-setup) is what upgrades the reminders from "changed, verdict unknown" to "changed, reviewed at this tree".

Conflict Handling

Script Status	Settings Status	Action
Missing	Missing	Install both
Identical	Present	Skip (up to date)
Different	Present	AskUserQuestion

Output

## Install Hooks Report

| Hook | Script | Settings | Status |
|------|--------|----------|--------|
| post-edit-format | ✅ | ✅ | installed |
| stop-guard | ✅ | ⏭️ | skipped (identical) |

Scripts: N installed | Settings entries: M merged