hookify-rules

# Writing Hookify Rules ## 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 ```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 | 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) ```markdown --- 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 ```bash 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 - `/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: ```markdown --- name: my-rule enabled: true event: bash pattern: dangerous_command --- Warning message here ```