writing-hookify-rules

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.

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

Example:

```yaml

event: bash

pattern: rm\s+-rf

```

Advanced Format (Multiple Conditions)

For complex rules with multiple conditions:

```markdown

---

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.

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:

```markdown

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

```

bash Events

Match Bash command patterns:

```markdown

---

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:

```markdown

---

event: file

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

---

Potentially problematic code pattern detected!

```

Match on different fields:

```markdown

---

event: file

conditions:

- field: file_path

operator: regex_match

pattern: \.tsx?$

- field: new_text

operator: regex_match

pattern: console\.log\(

---

Console.log in TypeScript file!

```

Common patterns:

• Debug code: console\.log\(, debugger, print\(
• Security risks: eval\(, innerHTML\s*=, dangerouslySetInnerHTML
• Sensitive files: \.env$, credentials, \.pem$
• Generated files: node_modules/, dist/, build/

stop Events

Match when agent wants to stop (completion checks):

```markdown

---

event: stop

pattern: .*

---

Before stopping, verify:

• [ ] Tests were run
• [ ] Build succeeded
• [ ] Documentation updated

```

Use for:

• Reminders about required steps
• Completion checklists
• Process enforcement

prompt Events

Match user prompt content (advanced):

```markdown

---

event: prompt

conditions:

- field: user_prompt

operator: contains

pattern: deploy to production

---

Production deployment checklist:

• [ ] Tests passing?
• [ ] Reviewed by team?
• [ ] Monitoring ready?

```

Regex Basics

Literal characters: Most characters match themselves

• rm matches "rm"
• console.log matches "console.log"

Special characters need escaping:

• . (any char) → \. (literal dot)
• ( ) → \( \) (literal parens)
• [ ] → \[ \] (literal brackets)

Common metacharacters:

• \s - whitespace (space, tab, newline)
• \d - digit (0-9)
• \w - word character (a-z, A-Z, 0-9, _)
• . - any character
• + - one or more
• * - zero or more
• ? - zero or one
• | - OR

Examples:

```

rm\s+-rf Matches: rm -rf, rm -rf

console\.log\( Matches: console.log(

(eval|exec)\( Matches: eval( or exec(

chmod\s+777 Matches: chmod 777, chmod 777

API_KEY\s*= Matches: API_KEY=, API_KEY =

```

Testing Patterns

Test regex patterns before using:

```bash

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

```

Or use online regex testers (regex101.com with Python flavor).

Common Pitfalls

Too broad:

```yaml

pattern: log # Matches "log", "login", "dialog", "catalog"

```

Better: console\.log\(|logger\.

Too specific:

```yaml

pattern: rm -rf /tmp # Only matches exact path

```

Better: rm\s+-rf

Escaping issues:

• YAML quoted strings: "pattern" requires double backslashes \\s
• YAML unquoted: pattern: \s works as-is
• Recommendation: Use unquoted patterns in YAML

Location: All rules in .claude/ directory

Naming: .claude/hookify.{descriptive-name}.local.md

Gitignore: Add .claude/*.local.md to .gitignore

Good names:

• hookify.dangerous-rm.local.md
• hookify.console-log.local.md
• hookify.require-tests.local.md
• hookify.sensitive-files.local.md

Bad names:

• hookify.rule1.local.md (not descriptive)
• hookify.md (missing .local)
• danger.local.md (missing hookify prefix)

Creating a Rule

1. Identify unwanted behavior
2. Determine which tool is involved (Bash, Edit, etc.)
3. Choose event type (bash, file, stop, etc.)
4. Write regex pattern
5. Create .claude/hookify.{name}.local.md file in project root
6. Test immediately - rules are read dynamically on next tool use

Refining a Rule

1. Edit the .local.md file
2. Adjust pattern or message
3. Test immediately - changes take effect on next tool use

Disabling a Rule

Temporary: Set enabled: false in frontmatter

Permanent: Delete the .local.md file

See ${CLAUDE_PLUGIN_ROOT}/examples/ for complete examples:

• dangerous-rm.local.md - Block dangerous rm commands
• console-log-warning.local.md - Warn about console.log
• sensitive-files-warning.local.md - Warn about editing .env files

Minimum viable rule:

```markdown

---

name: my-rule

enabled: true

event: bash

pattern: dangerous_command

---

Warning message here

```

Rule with conditions:

```markdown

---

name: my-rule

enabled: true

event: file

conditions:

- field: file_path

operator: regex_match

pattern: \.ts$

- field: new_text

operator: contains

pattern: any

---

Warning message

```

Event types:

• bash - Bash commands
• file - File edits
• stop - Completion checks
• prompt - User input
• all - All events

Field options:

• Bash: command
• File: file_path, new_text, old_text, content
• Prompt: user_prompt

Operators:

• regex_match, contains, equals, not_contains, starts_with, ends_with