Hookify Rule Syntax in Claude Code: A Complete Guide to Custom Hooks

Hookify rule syntax lets you define custom safety hooks in Claude Code using YAML front-matter inside markdown files placed in the .claude/ directory, supporting both simple regex patterns and advanced field-based conditions to warn or block specific tool usage.

The Hookify rule syntax enables developers to enforce project-specific guardrails in the anthropics/claude-code repository by reacting to bash commands, file edits, and prompt submissions without writing Python code. Each rule lives as a markdown file in your project's .claude/ directory and combines declarative YAML front-matter with a human-readable message body that Claude displays when the rule triggers.

Hookify Rule File Structure and Location

Store all rule files in your project's .claude/ directory using the naming convention .claude/hookify.{name}.local.md. According to the runtime implementation in plugins/hookify/hooks/pretooluse.py, the system scans this directory for *.local.md files and parses the YAML front-matter to register each hook.

Every rule file contains two distinct parts:

1. YAML front-matter enclosed between --- delimiters that defines the rule logic
2. Markdown body after the closing --- that serves as the warning or blocking message shown to Claude

Required YAML Front-Matter Fields

As documented in plugins/hookify/skills/writing-rules/SKILL.md, every rule must specify these fields:

• name: Unique identifier in kebab-case (e.g., block-dangerous-rm)
• enabled: Boolean toggle (true or false)
• event: Tool event to watch (bash, file, prompt, stop, or all)
• pattern or conditions: Matching criteria defining when the rule fires
• action: Either warn (default) or block—determines whether Claude proceeds after showing the message

All other YAML fields are ignored by the parser. The message body written in markdown after the front-matter appears in Claude's interface whenever the rule matches.

Pattern Matching Strategies

The Hookify rule syntax supports two distinct approaches for detecting tool usage: simple regex patterns and advanced field-based conditions.

Simple Pattern Matching

Use the pattern field to apply a Python regular expression against the entire event text. This works best for straightforward command detection or file path matching.

---
name: detect-rm-rf
enabled: true
event: bash
pattern: rm\s+-rf\s+/
action: warn
---

Advanced Condition Syntax

For precise control over complex scenarios, use the conditions field—a YAML list where every entry must evaluate to true for the rule to trigger. Each condition specifies:

• field: The specific attribute to inspect (varies by event type)
• operator: The comparison method
• pattern: The string or regex to match against

Available operators include:

• regex_match: Python-style regular expression (most common)
• contains: Substring must appear
• equals: Exact string equality
• not_contains: Substring must not appear
• starts_with: Prefix match
• ends_with: Suffix match

The fields available depend on the event type:

Event	Available Fields
bash	command
file	file_path, new_text, old_text, content
prompt	user_prompt
stop	transcript (session state representation)

Practical Hookify Rule Examples

The following examples demonstrate patterns found in plugins/hookify/README.md and the runtime hooks.

Warning on Dangerous Commands

This rule detects potentially destructive bash commands using a simple regex pattern:

---
name: block-dangerous-rm
enabled: true
event: bash
pattern: rm\s+-rf
---
⚠️ **Dangerous rm command detected!**
Please double-check the path before proceeding.

File location: .claude/hookify.block-dangerous-rm.local.md

Blocking Execution

Add action: block to the front-matter to prevent the matched tool from executing:

---
name: block-dangerous-rm
enabled: true
event: bash
pattern: rm\s+-rf
action: block
---
⛔️ **Execution blocked** – dangerous delete command.

Multi-Condition File Monitoring

Use multiple conditions to verify both the file path and content before triggering:

---
name: warn-sensitive-env
enabled: true
event: file
action: warn
conditions:
  - field: file_path
    operator: regex_match
    pattern: \.env$
  - field: new_text
    operator: contains
    pattern: API_KEY
---
🔐 **Sensitive credential added to .env**  
Consider moving it to a secret manager and ensure the file is git-ignored.

Session Stop Validation

Monitor the stop event to enforce workflow requirements before ending sessions:

---
name: require-tests-before-stop
enabled: true
event: stop
action: block
conditions:
  - field: transcript
    operator: not_contains
    pattern: npm test|pytest|cargo test
---
❗️ **Tests not detected** – please run your test suite before stopping.

Summary

• Hookify rules live in .claude/hookify.{name}.local.md files and use YAML front-matter to define trigger conditions
• The syntax supports five event types: bash, file, prompt, stop, and all
• Match using either a single pattern regex or an advanced conditions list with field-specific operators like regex_match, contains, or not_contains
• Actions are either warn (allow after notification) or block (prevent execution)
• All regular expressions use Python re module syntax as implemented in plugins/hookify/hooks/pretooluse.py

Frequently Asked Questions

Where do I place Hookify rule files?

Place them in your project's .claude/ directory with the naming format hookify.{name}.local.md. The plugin automatically discovers and loads these files during Claude Code initialization.

What is the difference between warn and block actions?

The warn action displays your message but allows Claude to proceed with the tool usage, while block prevents the action entirely until the user modifies their request. If omitted, action defaults to warn.

Can I combine multiple conditions in a single rule?

Yes. When using the conditions field (instead of a single pattern), provide a YAML list where all conditions must match for the rule to fire. Each condition specifies a field, operator, and pattern.

Which regex syntax does Hookify support?

Hookify uses Python regular expressions exactly as implemented by the standard library re module. This applies to all pattern values and regex_match operators throughout the rule syntax.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}