hooksmith

hooksmith

A Claude Code plugin for declarative hook rules. Define behavior as YAML — hooksmith evaluates rules at runtime. No build step.

How It Works

~/.config/hooksmith/hooks/*.yaml  ──→  hooksmith eval  ──→  JSON decision

One universal evaluator routes to the right rules at runtime. Claude Code fires an event, hooksmith checks matching rules, the first rule that triggers emits a decision.

Mechanism	How it works	Best for
match	Tests a field against a POSIX ERE pattern	Simple pattern matching, zero overhead
run	Executes a bash script (inline or file)	Complex logic, stateful checks
prompt	Injects a prompt for Claude to reason about	Nuanced, context-dependent policies

Installation

Requires Claude Code v2.1.91+.

claude plugin add ugudlado/hooksmith

Or install locally:

git clone https://github.com/ugudlado/hooksmith.git
claude --plugin-dir /path/to/hooksmith

Getting Started

Creating your first rule

Drop a YAML file and it's live next session:

# ~/.config/hooksmith/hooks/block-rm.yaml
rules:
  - name: block-rm
    on: PreToolUse Bash
    match: command =~ rm[[:space:]]+-rf[[:space:]]+(/|~|\$HOME)
    deny: "Blocked: destructive rm targeting system or home directory."

No build step needed. On SessionStart, hooksmith scans all rules, rebuilds its routing index, and registers the right events automatically.

Migrating existing hooks

If you have hooks in settings.json, convert them to YAML:

# Preview what will be converted (dry-run)
hooksmith convert

# Write the YAML rule files
hooksmith convert --apply

Then remove the converted entries from settings.json — hooksmith owns them now.

Starter Rules

Ready-to-use rules you can copy to ~/.config/hooksmith/hooks/. Each rule is a standalone YAML file — pick what you need.

Safety Guards

Block dangerous bash commands — catches rm -rf /, sudo, chmod 777, curl-pipe-sh:

# ~/.config/hooksmith/hooks/bash-safety-guard.yaml
rules:
  - name: bash-safety-guard
    on: PreToolUse Bash
    run: ~/.config/hooksmith/scripts/bash-safety-guard.sh
    deny: true

Process kill guard — only allows killing processes Claude started or processes inside the current repo:

# ~/.config/hooksmith/hooks/process-kill-guard.yaml
rules:
  - name: process-kill-guard
    on: PreToolUse Bash
    run: ~/.config/hooksmith/scripts/process-kill-guard.sh
    deny: true

Protected files — asks for confirmation before editing lock files and manifests:

# ~/.config/hooksmith/hooks/protected-files.yaml
rules:
  - name: protected-files
    on: PreToolUse Write|Edit
    run: ~/.config/hooksmith/scripts/protected-files.sh
    ask: true

Worktree boundary — prevents writes outside the active git worktree:

# ~/.config/hooksmith/hooks/worktree-boundary.yaml
rules:
  - name: worktree-boundary
    on: PreToolUse Write|Edit
    run: ~/.config/hooksmith/scripts/worktree-boundary.sh
    deny: true

Workflow Automation

Autopilot redirect — detects feature/bug requests and suggests /develop:

# ~/.config/hooksmith/hooks/autopilot-redirect.yaml
rules:
  - name: autopilot-redirect
    on: UserPromptSubmit
    prompt: |
      Analyze this user message: $USER_PROMPT
      If it's clearly a FEATURE or BUG request, respond with a workflow hint.
      Otherwise respond with {}.
    context: true

Loop detector — blocks Claude from getting stuck in retry loops:

# ~/.config/hooksmith/hooks/loop-detector.yaml
rules:
  - name: loop-detector
    on: Stop
    run: ~/.config/hooksmith/scripts/loop-detector.sh
    deny: true

Session Lifecycle

Git status at session start — gives Claude branch and change awareness:

# ~/.config/hooksmith/hooks/session-git-status.yaml
rules:
  - name: session-git-status
    on: SessionStart
    run: ~/.config/hooksmith/scripts/session-git-status.sh
    context: true

Post-compact reminders — re-injects critical context after compaction:

# ~/.config/hooksmith/hooks/post-compact-reminders.yaml
rules:
  - name: post-compact-reminders
    on: PostCompact
    run: ~/.config/hooksmith/scripts/post-compact-reminders.sh
    context: true

Development Tools

Auto-format — runs prettier/formatter after Write/Edit:

# ~/.config/hooksmith/hooks/auto-format.yaml
rules:
  - name: auto-format
    on: PostToolUse Write|Edit
    run: ~/.config/hooksmith/scripts/auto-format.sh
    context: true

Smart notifications — macOS alerts for permission prompts and idle:

# ~/.config/hooksmith/hooks/smart-notify.yaml
rules:
  - name: smart-notify
    on: Notification
    run: ~/.config/hooksmith/scripts/smart-notify.sh
    context: true