hookify

Easily create custom hooks to prevent unwanted behaviors by analyzing conversation patterns or from explicit instructions. Define rules via simple markdown files.

Installation

npx claude-plugins install @anthropics/claude-code-plugins/hookify

Contents

Folders: agents, commands, core, examples, hooks, matchers, skills, utils

Files: README.md

Documentation

Easily create custom hooks to prevent unwanted behaviors by analyzing conversation patterns or from explicit instructions.

Overview

The hookify plugin makes it simple to create hooks without editing complex hooks.json files. Instead, you create lightweight markdown configuration files that define patterns to watch for and messages to show when those patterns match.

Key features:

• 🎯 Analyze conversations to find unwanted behaviors automatically
• 📝 Simple markdown configuration files with YAML frontmatter
• 🔍 Regex pattern matching for powerful rules
• 🚀 No coding required - just describe the behavior
• 🔄 Easy enable/disable without restarting

Quick Start

1. Create Your First Rule

/hookify Warn me when I use rm -rf commands

This analyzes your request and creates .claude/hookify.warn-rm.local.md.

2. Test It Immediately

No restart needed! Rules take effect on the very next tool use.

Ask Claude to run a command that should trigger the rule:

Run rm -rf /tmp/test

You should see the warning message immediately!

Usage

Main Command: /hookify

With arguments:

/hookify Don't use console.log in TypeScript files

Creates a rule from your explicit instructions.

Without arguments:

/hookify

Analyzes recent conversation to find behaviors you’ve corrected or been frustrated by.

Helper Commands

List all rules:

/hookify:list

Configure rules interactively:

/hookify:configure

Enable/disable existing rules through an interactive interface.

Get help:

/hookify:help

Rule Configuration Format

Simple Rule (Single Pattern)

.claude/hookify.dangerous-rm.local.md:

---
name: block-dangerous-rm
enabled: true
event: bash
pattern: rm\s+-rf
action: block
---

⚠️ **Dangerous rm command detected!**

This command could delete important files. Please:
- Verify the path is correct
- Consider using a safer approach
- Make sure you have backups

Action field:

• warn: Shows warning but allows operation (default)
• block: Prevents operation from executing (PreToolUse) or stops session (Stop events)

Advanced Rule (Multiple Conditions)

.claude/hookify.sensitive-files.local.md:

---
name: warn-sensitive-files
enabled: true
event: file
action: warn
conditions:
  - field: file_path
    operator: regex_match
    pattern: \.env$|credentials|secrets
  - field: new_text
    operator: contains
    pattern: KEY
---

🔐 **Sensitive file edit detected!**

Ensure credentials are not hardcoded and file is in .gitignore.

All conditions must match for the rule to trigger.

Event Types

• bash: Triggers on Bash tool commands
• file: Triggers on Edit, Write, MultiEdit tools
• stop: Triggers when Claude wants to stop (for completion checks)
• prompt: Triggers on user prompt submission
• all: Triggers on all events

Pattern Syntax

Use Python regex syntax:

Tips:

• Use \s for whitespace
• Escape special chars: \. for literal dot
• Use | for OR: (foo|bar)
• Use .* to match anything
• Set action: block for dangerous operations
• Set action: warn (or omit) for informational warnings

Examples

Example 1: Block Dangerous Commands

---
name: block-destructive-ops
enabled: true
event: bash
pattern: rm\s+-rf|dd\s+if=|mkfs|format
action: block
---

🛑 **Destructive operation detected!**

This command can cause data loss. Operation blocked for safety.
Please verify the exact path and use a safer approach.

This rule blocks the operation - Claude will not be allowed to execute these commands.

Example 2: Warn About Debug Code

---
name: warn-debug-code
enabled: true
event: file
pattern: console\.log\(|debugger;|print\(
action: warn
---

🐛 **Debug code detected**

Remember to remove debugging statements before committing.

This rule warns but allows - Claude sees the message but can still proceed.

Example 3: Require Tests Before Stopping

---
name: require-tests-run
enabled: false
event: stop
action: block
conditions:
  - field: transcript
    operator: not_contains
    pattern: npm test|pytest|cargo test
---

**Tests not detected in transcript!**

Before stopping, please run tests to verify your changes work correctly.

This blocks Claude from stopping if no test commands appear in the session transcript. Enable only when you want strict enforcement.

Advanced Usage

Multiple Conditions

Check multiple fields simultaneously:

---
name: api-key-in-typescript
enabled: true
event: file
conditions:
  - field: file_path
    o

...(truncated)

## Included Skills

This plugin includes 1 skill definition:

### writing-rules

> This skill should be used when the user asks to "create a hookify rule", "write a hook rule", "configure hookify", "add a hookify rule", or needs guidance on hookify rule syntax and patterns.

<details>
<summary>View skill definition</summary>

# Writing Hookify Rules

## Overview

Hookify rules are markdown files with YAML frontmatter that define patterns to watch for and messages to show when those patterns match. Rules are stored in `.claude/hookify.{rule-name}.local.md` files.

## Rule File Format

### Basic Structure

```markdown
---
name: rule-identifier
enabled: true
event: bash|file|stop|prompt|all
pattern: regex-pattern-here
---

Message to show Claude when this rule triggers.
Can include markdown formatting, warnings, suggestions, etc.

Frontmatter Fields

name (required): Unique identifier for the rule

• Use kebab-case: warn-dangerous-rm, block-console-log
• Be descriptive and action-oriented
• Start with verb: warn, prevent, block, require, check

enabled (required): Boolean to activate/deactivate

• true: Rule is active
• false: Rule is disabled (won’t trigger)
• Can toggle without deleting rule

event (required): Which hook event to trigger on

• bash: Bash tool commands
• file: Edit, Write, MultiEdit tools
• stop: When agent wants to stop
• prompt: When user submits a prompt
• all: All events

action (optional): What to do when rule matches

• warn: Show message but allow operation (default)
• block: Prevent operation (PreToolUse) or stop session (Stop events)
• If omitted, defaults to warn

pattern (simple format): Regex pattern to match

• Used for simple single-condition rules
• Matches against command (bash) or new_text (file)
• Python regex syntax

…(truncated)

Source

View on GitHub