hookify-rules

name	hookify-rules
description	Use when creating or editing hookify rule files (ECC plugin format) that intercept bash commands, file edits, or prompt events — rule syntax, patterns, and configuration guidance.

Writing Hookify Rules

Prerequisite: the /hookify* commands referenced below ship with the ECC plugin — without ECC installed, write the rule files by hand using this reference. This plugin itself ships no hooks; runtime hook enforcement in this setup lives in the agent-dashboard plugin.

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

Field	Required	Values	Description
name	Yes	kebab-case string	Unique identifier (verb-first: warn-, block-, require-*)
enabled	Yes	true/false	Toggle without deleting
event	Yes	bash/file/stop/prompt/all	Which hook event triggers this
action	No	warn/block	warn (default) shows message; block prevents operation
pattern	Yes*	regex string	Pattern to match (*or use conditions for complex rules)

Advanced Format (Multiple Conditions)

---
name: warn-env-api-keys
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 by event:

• bash: command
• file: file_path, new_text, old_text, content
• prompt: user_prompt

Operators: regex_match, contains, equals, not_contains, starts_with, ends_with

All conditions must match for rule to trigger.

Event Type Guide

bash Events

Match Bash command patterns:

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

file Events

Match Edit/Write/MultiEdit operations:

• Debug code: console\.log\(, debugger
• Security risks: eval\(, innerHTML\s*=
• Sensitive files: \.env$, credentials, \.pem$

stop Events

Completion checks and reminders. Pattern .* matches always.

prompt Events

Match user prompt content for workflow enforcement.

Pattern Writing Tips

Regex Basics

• Escape special chars: . to \., ( to \(
• \s whitespace, \d digit, \w word char
• + one or more, * zero or more, ? optional
• | OR operator

Common Pitfalls

• Too broad: log matches "login", "dialog" — use console\.log\(
• Too specific: rm -rf /tmp — use rm\s+-rf
• YAML escaping: Use unquoted patterns; quoted strings need \\s

Testing

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

File Organization

• Location: .claude/ directory in project root
• Naming: .claude/hookify.{descriptive-name}.local.md
• Gitignore: Add .claude/*.local.md to .gitignore

Commands (ECC plugin)

• /hookify [description] - Create new rules (auto-analyzes conversation if no args)
• /hookify-list - View all rules in table format
• /hookify-configure - Toggle rules on/off interactively
• /hookify-help - Full documentation

Quick Reference

Minimum viable rule:

---
name: my-rule
enabled: true
event: bash
pattern: dangerous_command
---
Warning message here