writing-rules

Writing Hookify Rules

Overview

Hookify rules are markdown files with YAML frontmatter that define patterns to watch for and messages to display when those patterns match. Store rules as .md files in .claude/hookify-plus/. Rules are read dynamically — changes take effect on the next tool use.

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.
Include markdown formatting, warnings, and suggestions.

Frontmatter Fields

name (required): Unique identifier for the rule.

• Use kebab-case: warn-dangerous-rm, block-console-log
• Start with a verb: warn, prevent, block, require, check

enabled (required): Boolean to activate/deactivate.

• Set true to activate, false to disable without deleting the rule.

event (required): Hook event to trigger on.

• bash — Bash tool commands
• file — Edit, Write, MultiEdit, Update tools
• read — Read, Glob, Grep, LS tools (reads, not modifications)
• stop — When the agent wants to stop
• prompt — When the user submits a prompt
• all — All events

action (optional): Behavior when the rule matches.

• warn — Show message but allow operation (default)
• block — Prevent operation (PreToolUse) or stop session (Stop events)

warn_once (optional): Boolean. Only warn once per session. Subsequent matches are silently ignored.

warn_interval (optional): Integer. Warn every N matches. Set to 0 to warn every time (default behavior).

tool_matcher (optional): String. Override which tools a rule matches, instead of using the default tool set for the event type.

pattern (simple format): Regex pattern to match (case-insensitive).

• Matches against command (bash) or new_text (file).
• Use Python regex syntax.

Example:

event: bash
pattern: rm\s+-rf

Advanced Format (Multiple Conditions)

For rules with multiple conditions, replace pattern with a conditions array. All conditions must match for the rule to trigger.