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

> Master Hookify rule syntax in Claude Code. Learn to define custom safety hooks with YAML and Markdown using regex patterns and field-based conditions for secure tool usage.

- Repository: [Anthropic/claude-code](https://github.com/anthropics/claude-code)
- Tags: deep-dive
- Published: 2026-04-02

---

**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`](https://github.com/anthropics/claude-code/blob/main/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`](https://github.com/anthropics/claude-code/blob/main/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.

```markdown
---
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`](https://github.com/anthropics/claude-code/blob/main/plugins/hookify/README.md) and the runtime hooks.

### Warning on Dangerous Commands

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

```markdown
---
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`](https://github.com/anthropics/claude-code/blob/main/.claude/hookify.block-dangerous-rm.local.md)

### Blocking Execution

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

```markdown
---
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:

```markdown
---
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:

```markdown
---
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`](https://github.com/anthropics/claude-code/blob/main/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.