Writing Hookify Rules

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

---
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

**Example:**

event: bash
pattern: rm\s+-rf

Advanced Format (Multiple Conditions)

For complex rules with multiple conditions:

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

You're adding an API key to a .env file. Ensure this file is in .gitignore!

**Condition fields:**

• `field`: Which field to check
• For bash: `command`
• For file: `file_path`, `new_text`, `old_text`, `content`
• `operator`: How to match
• `regex_match`: Regex pattern matching
• `contains`: Substring check
• `equals`: Exact match
• `not_contains`: Substring must NOT be present
• `starts_with`: Prefix check
• `ends_with`: Suffix check
• `pattern`: Pattern or string to match

**All conditions must match for rule to trigger.**

Message Body

The markdown content after frontmatter is shown to Claude when the rule triggers.

**Good messages:**

• Explain what was detected
• Explain why it's problematic
• Suggest alternatives or best practices
• Use formatting for clarity (bold, lists, etc.)

**Example:**

⚠️ **Console.log detected!**

You're adding console.log to production code.

**Why this matters:**
- Debug logs shouldn't ship to production
- Console.log can expose sensitive data
- Impacts browser performance

**Alternatives:**
- Use a proper logging library
- Remove before committing
- Use conditional debug builds

Event Type Guide

bash Events

Match Bash command patterns:

---
event: bash
pattern: sudo\s+|rm\s+-rf|chmod\s+777
---

Dangerous command detected!

**Common patterns:**

• Dangerous commands: `rm\s+-rf`, `dd\s+if=`, `mkfs`
• Privilege escalation: `sudo\s+`, `su\s+`
• Permission issues: `chmod\s+777`, `chown\s+root`

file Events

Match Edit/Write/MultiEdit operations:

---
event: file
pattern: console\.log\(|eval\(|innerHTML\s*=
---

Potentially problematic code pattern detected!

**Match on different fields:**

---
event: file
conditions:
  - field: file_path
    operator: regex_match
    pattern: \.tsx?$
  - field: new_text
    operator: regex_match

<!-- truncated -->