claude-hooks

claude-hooks

Safety and automation hooks for Claude Code.

Plugins

Installation

Via Claude Code Plugin System (Recommended)

1. Add this repository as a marketplace source:

/plugin marketplace add steeef/claude-hooks

2. Install the plugins you want:

/plugin install command-safety@steeef/claude-hooks
/plugin install git-hooks@steeef/claude-hooks
/plugin install file-protection@steeef/claude-hooks
/plugin install notifications@steeef/claude-hooks

Manual Installation

git clone https://github.com/steeef/claude-hooks.git
cd claude-hooks

export CLAUDE_HOOKS_DIR="$HOME/code/claude-hooks"

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_HOOKS_DIR/plugins/command-safety/hooks/command_hook.py"
          },
          {
            "type": "command",
            "command": "$CLAUDE_HOOKS_DIR/plugins/git-hooks/hooks/git_pre_hook.py"
          }
        ]
      },
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_HOOKS_DIR/plugins/file-protection/hooks/file_hook.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_HOOKS_DIR/plugins/git-hooks/hooks/cleanup_hook.py"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_HOOKS_DIR/plugins/notifications/hooks/notification_hook.sh"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_HOOKS_DIR/plugins/notifications/hooks/notification_hook.sh"
          }
        ]
      }
    ]
  }
}

Plugin Details

command-safety

Blocks potentially destructive commands:

• rm on git-tracked files (allows removal of ignored files like build artifacts)
• kubectl delete, kubectl scale --replicas=0, kubectl cordon, kubectl drain
• terraform destroy

git-hooks

Enforces safe git workflows:

• Blocks commits to main/master - forces feature branch workflow (configurable allowlist)
• Blocks dangerous checkout - prevents git checkout main -- file overwrites
• Blocks dangerous add patterns - prevents git add -A, --force flags
• Suggests worktrees - recommends git worktrees for feature branches
• Cleanup hook - clears branch tracking state after commands

file-protection

Protects important files and encourages worktree workflow:

• Worktree edit guard - deny-then-ask speed bump for edits outside a git worktree (tied to session_id, not a timer)
• Blocks CLAUDE.md edits - project instructions should be edited manually
• Large file warning - warns before editing files over 10,000 lines (speed bump pattern with flag file)

env-protection

Prevents accidental exposure of secrets in .env files:

• Blocks .env reads - both Bash commands (cat .env, grep .env) and Read tool
• Allows safe operations - ls, mv, cp, touch on .env files
• Allows templates - .env.example, .env.template, .env.sample
• Safe CLI - env-safe script for inspecting variable names without values

notifications

Desktop notifications on macOS using osascript:

• Triggers on Stop events (task completion)
• Triggers on Notification events

Development

Requirements: Python 3.11+

# Install dependencies
uv sync

# Run tests
uv run pytest -v

# Run pre-commit hooks
uvx --with pre-commit-uv pre-commit run --all-files

Acknowledgments

Based on pchalasani/claude-code-tools.

License