Table of Contents

• Overview
• Quick Start
• Rule File Format
• Frontmatter Fields
• Event Types
• Advanced Conditions
• Operators
• Field Reference
• Pattern Writing
• Regex Basics
• Examples
• Test Patterns
• Example Rules
• Block Destructive Commands
• Warn About Debug Code
• Require Tests
• Protect Production Files
• Management
• Related Skills
• Best Practices

Hookify Rule Writing Guide

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.

Quick Start

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

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

🛑 **Dangerous rm command detected!**

This command could delete important files.

Verification: Run the command with --help flag to verify availability.

The rule activates immediately - no restart needed!

Rule File Format

Frontmatter Fields

name (required): Unique identifier (kebab-case) enabled (required): true or false event (required): bash, file, stop, prompt, or all action (optional): warn (default) or block pattern (simple): Regex pattern to match

Event Types

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

Advanced Conditions

For multiple field checks:

---
name: warn-env-edits
enabled: true
event: file
action: warn
conditions:
  - field: file_path
    operator: regex_match
    pattern: \.env$
  - field: new_text
    operator: contains
    pattern: API_KEY
---

🔐 **API key in .env file!**
Ensure file is in .gitignore.

Verification: Run the command with --help flag to verify availability.

Operators

• regex_match: Pattern matching
• contains: Substring check
• equals: Exact match
• not_contains: Must NOT contain
• starts_with: Prefix check
• ends_with: Suffix check

Field Reference

bash events: command file events: file_path, new_text, old_text, content prompt events: user_prompt stop events: transcript

Pattern Writing

Regex Basics

• \s - whitespace
• \d - digit
• \w - word character
• . - any character (use \. for literal dot)
• + - one or more
• * - zero or more
• | - OR

Examples

**Verification:** Run the command with `--help` flag to verify availability.
rm\s+-rf          → rm -rf
console\.log\(    → console.log(
chmod\s+777       → chmod 777

Verification: Run the command with --help flag to verify availability.

Test Patterns

python3 -c "import re; print(re.search(r'pattern', 'text'))"

Verification: Run the command with --help flag to verify availability.

Example Rules

Block Destructive Commands

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

🛑 **Destructive operation blocked!**
Can cause data loss.

Verification: Run the command with --help flag to verify availability.

Warn About Debug Code

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

🐛 **Debug code detected!**
Remove before committing.

Verification: Run the command with --help flag to verify availability.

Require Tests

---
name: require-tests
enabled: true
event: stop
action: warn
conditions:
  - field: transcript
    operator: not_contains
    pattern: pytest|npm test
---

⚠️ **Tests not run!**
Please verify changes.

Verification: Run pytest -v to verify tests pass.

Protect Production Files

---
name: protect-prod
enabled: true
event: file
action: block
conditions:
  - field: file_path
    operator: regex_match
    pattern: /production/|\.prod\.
---

🚨 **Production file!**
Requires review.

Verification: Run the command with --help flag to verify availability.

Management

Enable/Disable: Edit .local.md file: enabled: false

Delete:

rm .claude/hookify.my-rule.local.md

Verification: Run the command with --help flag to verify availability.

List:

/hookify:list

Verification: Run the command with --help flag to verify availability.

Related Skills

• abstract:hook-scope-guide - Hook placement decisions
• abstract:hook-authoring - SDK hook development
• abstract:hooks-eval - Hook evaluation

Best Practices

1. Start with simple patterns
2. Test regex thoroughly
3. Use clear, helpful messages
4. Prefer warnings over blocks initially
5. Name rules descriptively
6. Document intent in messages

Troubleshooting

Common Issues

Command not found Ensure all dependencies are installed and in PATH

Permission errors Check file permissions and run with appropriate privileges

Unexpected behavior Enable verbose logging with --verbose flag