Skip to main content
command CX Codex

install-hook — Claude Code command: what it does, how to install

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

MIT ★ 907 updated 2025-11-12

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/install-hook.md
Open on GitHub

What install-hook 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.

What it helps with

  • 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 for the agent

  • /install-hook generated-hooks/auto-format-python user
  • /install-hook generated-hooks/test-runner project
  • /install-hook generated-hooks/git-auto-add

How to install install-hook

Manually: put the files in place

.claude/commands/install-hook.md

Call it with /install-hook. For all projects use ~/.claude/commands/

Questions about install-hook

How to install install-hook in Claude Code?

Place the command file at .claude/commands/install-hook.md inside your repository.

What does install-hook do?

It checks hook.json for syntax and security violations, makes a backup copy, and merges the hook into user or project settings.json.

Why does a newly added hook fail to run?

Claude Code requires a full restart before reading changes made to settings.json files.

Source text

install-hook.md · MIT
# /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": [
      {
        "matcher": {"tool_names": ["Write"]},
        "hooks": [{"type": "command", "command": "existing hook"}]
      }
    ]
  }
}
```

**After installing new hook**:
```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": {"tool_names": ["Write"]},
        "hooks": [{"type": "command", "command": "existing hook"}]
      },
      {
        "matcher": {"tool_names": ["Write", "Edit"], "paths": ["**/*.py"]},
        "hooks": [{"type": "command", "command": "new hook"}]
      }
    ]
  }
}
```

**Key points**:
- ✅ Existing hooks preserved
- ✅ Other settings untouched
- ✅ Proper event type grouping
- ✅ Backup created before changes

---

## Backup and Recovery

**Automatic backups**:
- Created before every installation
- Named: `settings.json.backup`
- Location: Same directory as settings.json

**Restore from backup**:
```bash
# User-level
cp ~/.claude/settings.json.backup ~/.claude/settings.json

# Project-level
cp .claude/settings.json.backup .claude/settings.json
```

**After restore**: Restart Claude Code

---

## Uninstalling Hooks

**Manual uninstallation**:

1. Open settings file:
   ```bash
   # User-level
   vim ~/.claude/settings.json

   # Project-level
   vim .claude/settings.json
   ```

2. Find and remove the hook entry under its event type

3. Save and restart Claude Code

**Future**: Automated `/uninstall-hook` command planned

---

## Related Commands

**Before installing**:
- `/build hook` - Generate hook configuration
- `/validate-output hook` - Validate before installation

**After installing**:
- `/factory-status` - See all installed hooks
- `/test-factory` - Test hook functionality

**Managing hooks**:
- Run `/hooks` in Claude Code to view and manage all hooks
- Use Claude Code's settings menu to edit hook configuration

---

## Common Workflows

### Build → Validate → Install → Test

```bash
# 1. Build hook
/build hook

[Answer questions, hook generated]

# 2. Validate (CRITICAL for security)
/validate-output hook generated-hooks/my-hook

# 3. Install
/install-hook generated-hooks/my-hook user

# 4. Restart Claude Code
claude --continue

# 5. Test
[Trigger the hook event - e.g., edit a file for PostToolUse]
```

---

### Quick Install (If Already Validated)

```bash
# Already validated during generation
/install-hook generated-hooks/auto-format-python project
[Restart Claude Code]
```

---

## Tips

**Choosing user vs project level**:
- **User-level**: For hooks you want in ALL projects (formatters, notifications)
- **Project-level**: For project-specific hooks (tests, deployment, custom workflows)

**Testing hooks**:
- Start small: Install to project level first
- Test thoroughly before installing user-level
- Use `/hooks` command in Claude Code to view active hooks

**Managing multiple hooks**:
- Install one at a time
- Test each hook individually
- Check `/factory-status` to see all installed hooks

**Troubleshooting**:
- If hook doesn't run: Check event type matches your action
- If errors occur: Check hook validation with `/validate-output hook`
- If conflicts: Review settings.json manually
- Always check backup if something goes wrong

---

## Platform Notes

**macOS**:
- Hooks can use `osascript`, `afplay` for notifications/sounds
- Settings location: `~/.claude/settings.json`

**Linux**:
- Hooks can use `notify-send`, `paplay` for notifications/sounds
- Settings location: `~/.claude/settings.json`

**Windows**:
- Settings location: `%USERPROFILE%\.claude\settings.json`
- Use cross-platform tools (git, language-specific formatters)

---

**Safe hook installation with automatic validation!** 🔧✅

© alirezarezvani · MIT · alirezarezvani/claude-code-skill-factory

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

From the same set36

The whole set →
install-skill Prints step-by-step instructions for placing a generated skill or agent where Claude can find it, with the install routes laid out to pick from. CX Codex +1 ★ 907repo stars factory-guide factory-guide routes requests for building skills, prompts, agents, and hooks by handing tasks off to dedicated subagents. CX Codex ★ 907repo stars test-factory The test-factory command checks generated skills, agents, and prompts by suggesting ways to invoke them and what to verify in their output. CX Codex +1 ★ 907repo stars factory-status factory-status prints one report on everything the skill factory has produced so far: what passed checks, what is installed, and which step comes next. CX Codex +1 ★ 907repo stars sync-todos-to-github sync-todos-to-github turns a TodoWrite task list into a GitHub planning issue and starts follow-up automation. Useful for sprint plans and saved work checkpoints. CX Codex +1 ★ 907repo stars validate-output validate-output runs a checklist over a freshly generated skill, prompt, subagent or hook and names what needs fixing. A skill that passes gets zipped. CX Codex +1 ★ 907repo stars agent-factory agent-factory generates production-ready Claude Code sub-agent files with YAML frontmatter, tool permissions, and MCP server integrations. CX Codex +1 ★ 907repo stars content-trend-researcher content-trend-researcher studies topic signals and audience intent across content platforms, then builds article outlines. Use it to validate ideas and spot underserved subjects. CX Codex +1 ★ 907repo stars

Project sponsors

Companies that keep this analytics open