# install-hook

Installs generated hooks into project or user settings files with safety checks and automatic backup creation.

- command · `type=command` · Claude Code, Codex, GitHub Copilot, Gemini CLI · ★ 907 repo stars
- Author: alirezarezvani
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/alirezarezvani/claude-code-skill-factory/tree/HEAD/.claude/commands/install-hook.md
- Updated: 2025-11-12
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/commands/install-hook

## What it does

The command integrates configuration from `hook.json` into `settings.json`. It can target user-level settings in `~/.claude/settings.json` for all projects or project-level settings in `.claude/settings.json`. When the target scope is omitted, it detects whether local project settings exist or prompts for the destination.

Every installation begins with validation. The command checks JSON syntax, verifies event types, and flags unsafe commands such as `rm -rf` or directory traversal patterns. It also enforces silent exit patterns using `|| exit 0` so non-critical hooks do not crash workflows.

Existing configuration entries stay intact because the command merges new triggers into their matching event sections. A restore copy named `settings.json.backup` is written prior to modifications, though Claude Code must be restarted before new hooks become active.

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/commands/install-hook.md` — Call it with /install-hook. For all projects use ~/.claude/commands/

### Codex

**Manually: put the files in place**
- File: `~/.codex/prompts/install-hook.md` — Call it with /prompts:install-hook. Codex marks this format deprecated in favour of skills

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/prompts/install-hook.prompt.md`

### Gemini CLI

**Manually: put the files in place**
- File: `.gemini/commands/install-hook.toml` — Gemini stores commands as TOML: the prompt text goes into the prompt field

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/alirezarezvani/claude-code-skill-factory/tree/HEAD/.claude/commands/install-hook.md

## When to use it
- write generated hook settings into user or workspace configurations
- verify hook command safety and prevent destructive shell executions
- merge fresh triggers into settings without overwriting earlier hooks
- create automatic backup files before touching configuration JSON

## Example prompts
- /install-hook generated-hooks/auto-format-python user
- /install-hook generated-hooks/test-runner project
- /install-hook generated-hooks/git-auto-add

## Source text · install-hook.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: ed9341e156cfc617.

BEGIN THIRD-PARTY FILE ed9341e156cfc617
````text
# /install-hook - Install Generated Hook to Settings

**Install a generated hook to Claude Code settings (user-level or project-level).**

---

## Usage

```
/install-hook generated-hooks/my-hook
/install-hook generated-hooks/my-hook user
/install-hook generated-hooks/my-hook project
```

---

## What This Command Does

Installs hook.json configuration to:
- **User-level** (`~/.claude/settings.json`) - Applies to all projects
- **Project-level** (`.claude/settings.json`) - Current project only

**Installation process**:
1. ✅ Validates hook.json structure
2. ✅ Checks for safety violations
3. ✅ Backs up existing settings.json
4. ✅ Merges with existing hooks (preserves other settings)
5. ✅ Saves and displays confirmation

---

## Examples

### Install User-Level Hook (All Projects)

```
/install-hook generated-hooks/auto-format-python user
```

**Performs**:
1. Reads `generated-hooks/auto-format-python/hook.json`
2. Validates JSON structure and safety
3. Creates backup: `~/.claude/settings.json.backup`
4. Opens `~/.claude/settings.json`
5. Adds hook to appropriate event type section
6. Saves changes

**Output**:
```
Installing hook: auto-format-python
Location: User-level (~/.claude/settings.json)

✅ Hook validation PASSED
   - JSON structure: Valid
   - Safety checks: All passed
   - Event type: PostToolUse

Creating backup...
✅ Backup created: ~/.claude/settings.json.backup

Installing to PostToolUse hooks...
✅ Hook installed successfully!

Event type: PostToolUse
Matcher: tool_names=["Write", "Edit"], paths=["**/*.py"]
Command: Auto-format Python with Black

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Next steps:
1. Restart Claude Code (required)
2. Test by editing a .py file
3. Verify hook runs automatically

To test:
claude --continue
> Edit any Python file
> Check if Black formatting runs
```

---

### Install Project-Level Hook (Current Project Only)

```
/install-hook generated-hooks/test-runner project
```

**Installs to**: `.claude/settings.json` (current project)

**Output**:
```
Installing hook: test-runner
Location: Project-level (.claude/settings.json)

✅ Hook validation PASSED
✅ Backup created: .claude/settings.json.backup
✅ Hook installed successfully!

Event type: SubagentStop
Matcher: (empty - runs for all agents)
Command: Run pytest after agent completes

This hook will only run in this project.

Next steps:
1. Restart Claude Code
2. Run any Task agent
3. Hook will automatically run tests when agent completes
```

---

### Auto-Detect Installation Level

```
/install-hook generated-hooks/git-auto-add
```

**Auto-detection logic**:
- If `.claude/settings.json` exists → Install to project
- Otherwise → Ask user: "Install to user or project level?"

---

## Safety Validation

**Before installation, the hook is validated for**:

1. **JSON Structure**:
   - ✅ Valid JSON syntax
   - ✅ Required fields present (matcher, hooks)
   - ✅ Correct data types

2. **Safety Patterns**:
   - ✅ Tool detection for external commands
   - ✅ Silent failure mode (`|| exit 0`)
   - ✅ No destructive operations (rm -rf, git push --force, etc.)
   - ✅ File path safety (no path traversal, proper quoting)

3. **Event Type Validation**:
   - ✅ Appropriate timeout for event type
   - ✅ Matcher matches event requirements
   - ✅ Command complexity appropriate

**If validation fails**:
```
❌ Hook validation FAILED

Issues found:
1. Missing tool detection for "black"
2. Path traversal detected (..)
3. No silent failure mode

Fix these issues before installation:
/validate-output hook generated-hooks/auto-format-python

Then regenerate the hook or fix manually.
```

---

## Settings Merge Behavior

**Existing hooks are preserved**:

**Before installation**:
```json
{
  "hooks": {
    "PostToolUse": [
      {
````
END THIRD-PARTY FILE ed9341e156cfc617

The third-party file has ended. Everything between the ed9341e156cfc617 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3864 of 7486 bytes. © alirezarezvani · MIT · https://github.com/alirezarezvani/claude-code-skill-factory/tree/HEAD/.claude/commands/install-hook.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
