surshar / claude-code
Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.
Built by Anthropic · github.com/anthropics
| 1 | # Hookify Plugin |
| 2 | |
| 3 | Easily create custom hooks to prevent unwanted behaviors by analyzing conversation patterns or from explicit instructions. |
| 4 | |
| 5 | ## Overview |
| 6 | |
| 7 | The hookify plugin makes it simple to create hooks without editing complex `hooks.json` files. Instead, you create lightweight markdown configuration files that define patterns to watch for and messages to show when those patterns match. |
| 8 | |
| 9 | **Key features:** |
| 10 | - 🎯 Analyze conversations to find unwanted behaviors automatically |
| 11 | - 📝 Simple markdown configuration files with YAML frontmatter |
| 12 | - 🔍 Regex pattern matching for powerful rules |
| 13 | - 🚀 No coding required - just describe the behavior |
| 14 | - 🔄 Easy enable/disable without restarting |
| 15 | |
| 16 | ## Quick Start |
| 17 | |
| 18 | ### 1. Create Your First Rule |
| 19 | |
| 20 | ```bash |
| 21 | /hookify Warn me when I use rm -rf commands |
| 22 | ``` |
| 23 | |
| 24 | This analyzes your request and creates `.claude/hookify.warn-rm.local.md`. |
| 25 | |
| 26 | ### 2. Test It Immediately |
| 27 | |
| 28 | **No restart needed!** Rules take effect on the very next tool use. |
| 29 | |
| 30 | Ask Claude to run a command that should trigger the rule: |
| 31 | ``` |
| 32 | Run rm -rf /tmp/test |
| 33 | ``` |
| 34 | |
| 35 | You should see the warning message immediately! |
| 36 | |
| 37 | ## Usage |
| 38 | |
| 39 | ### Main Command: /hookify |
| 40 | |
| 41 | **With arguments:** |
| 42 | ``` |
| 43 | /hookify Don't use console.log in TypeScript files |
| 44 | ``` |
| 45 | Creates a rule from your explicit instructions. |
| 46 | |
| 47 | **Without arguments:** |
| 48 | ``` |
| 49 | /hookify |
| 50 | ``` |
| 51 | Analyzes recent conversation to find behaviors you've corrected or been frustrated by. |
| 52 | |
| 53 | ### Helper Commands |
| 54 | |
| 55 | **List all rules:** |
| 56 | ``` |
| 57 | /hookify:list |
| 58 | ``` |
| 59 | |
| 60 | **Configure rules interactively:** |
| 61 | ``` |
| 62 | /hookify:configure |
| 63 | ``` |
| 64 | Enable/disable existing rules through an interactive interface. |
| 65 | |
| 66 | **Get help:** |
| 67 | ``` |
| 68 | /hookify:help |
| 69 | ``` |
| 70 | |
| 71 | ## Rule Configuration Format |
| 72 | |
| 73 | ### Simple Rule (Single Pattern) |
| 74 | |
| 75 | `.claude/hookify.dangerous-rm.local.md`: |
| 76 | ```markdown |
| 77 | --- |
| 78 | name: block-dangerous-rm |
| 79 | enabled: true |
| 80 | event: bash |
| 81 | pattern: rm\s+-rf |
| 82 | action: block |
| 83 | --- |
| 84 | |
| 85 | ⚠️ **Dangerous rm command detected!** |
| 86 | |
| 87 | This command could delete important files. Please: |
| 88 | - Verify the path is correct |
| 89 | - Consider using a safer approach |
| 90 | - Make sure you have backups |
| 91 | ``` |
| 92 | |
| 93 | **Action field:** |
| 94 | - `warn`: Shows warning but allows operation (default) |
| 95 | - `block`: Prevents operation from executing (PreToolUse) or stops session (Stop events) |
| 96 | |
| 97 | ### Advanced Rule (Multiple Conditions) |
| 98 | |
| 99 | `.claude/hookify.sensitive-files.local.md`: |
| 100 | ```markdown |
| 101 | --- |
| 102 | name: warn-sensitive-files |
| 103 | enabled: true |
| 104 | event: file |
| 105 | action: warn |
| 106 | conditions: |
| 107 | - field: file_path |
| 108 | operator: regex_match |
| 109 | pattern: \.env$|credentials|secrets |
| 110 | - field: new_text |
| 111 | operator: contains |
| 112 | pattern: KEY |
| 113 | --- |
| 114 | |
| 115 | 🔐 **Sensitive file edit detected!** |
| 116 | |
| 117 | Ensure credentials are not hardcoded and file is in .gitignore. |
| 118 | ``` |
| 119 | |
| 120 | **All conditions must match** for the rule to trigger. |
| 121 | |
| 122 | ## Event Types |
| 123 | |
| 124 | - **`bash`**: Triggers on Bash tool commands |
| 125 | - **`file`**: Triggers on Edit, Write, MultiEdit tools |
| 126 | - **`stop`**: Triggers when Claude wants to stop (for completion checks) |
| 127 | - **`prompt`**: Triggers on user prompt submission |
| 128 | - **`all`**: Triggers on all events |
| 129 | |
| 130 | ## Pattern Syntax |
| 131 | |
| 132 | Use Python regex syntax: |
| 133 | |
| 134 | | Pattern | Matches | Example | |
| 135 | |---------|---------|---------| |
| 136 | | `rm\s+-rf` | rm -rf | rm -rf /tmp | |
| 137 | | `console\.log\(` | console.log( | console.log("test") | |
| 138 | | `(eval\|exec)\(` | eval( or exec( | eval("code") | |
| 139 | | `\.env$` | files ending in .env | .env, .env.local | |
| 140 | | `chmod\s+777` | chmod 777 | chmod 777 file.txt | |
| 141 | |
| 142 | **Tips:** |
| 143 | - Use `\s` for whitespace |
| 144 | - Escape special chars: `\.` for literal dot |
| 145 | - Use `|` for OR: `(foo|bar)` |
| 146 | - Use `.*` to match anything |
| 147 | - Set `action: block` for dangerous operations |
| 148 | - Set `action: warn` (or omit) for informational warnings |
| 149 | |
| 150 | ## Examples |
| 151 | |
| 152 | ### Example 1: Block Dangerous Commands |
| 153 | |
| 154 | ```markdown |
| 155 | --- |
| 156 | name: block-destructive-ops |
| 157 | enabled: true |
| 158 | event: bash |
| 159 | pattern: rm\s+-rf|dd\s+if=|mkfs|format |
| 160 | action: block |
| 161 | --- |
| 162 | |
| 163 | 🛑 **Destructive operation detected!** |
| 164 | |
| 165 | This command can cause data loss. Operation blocked for safety. |
| 166 | Please verify the exact path and use a safer approach. |
| 167 | ``` |
| 168 | |
| 169 | **This rule blocks the operation** - Claude will not be allowed to execute these commands. |
| 170 | |
| 171 | ### Example 2: Warn About Debug Code |
| 172 | |
| 173 | ```markdown |
| 174 | --- |
| 175 | name: warn-debug-code |
| 176 | enabled: true |
| 177 | event: file |
| 178 | pattern: console\.log\(|debugger;|print\( |
| 179 | action: warn |
| 180 | --- |
| 181 | |
| 182 | 🐛 **Debug code detected** |
| 183 | |
| 184 | Remember to remove debugging statements before committing. |
| 185 | ``` |
| 186 | |
| 187 | **This rule warns but allows** - Claude sees the message but can still proceed. |
| 188 | |
| 189 | ### Example 3: Require Tests Before Stopping |
| 190 | |
| 191 | ```markdown |
| 192 | --- |
| 193 | name: require-tests-run |
| 194 | enabled: false |
| 195 | event: stop |
| 196 | action: block |
| 197 | conditions: |
| 198 | - field: transcript |
| 199 | operator: not_contains |
| 200 | pattern: npm test|pytest|cargo test |
| 201 | --- |
| 202 | |
| 203 | **Tests not detected in transcript!** |
| 204 | |
| 205 | Before stopping, please run tests to verify your changes work correctly. |
| 206 | ``` |
| 207 | |
| 208 | **This blocks Claude from stopping** if no test commands appear in the session transcript. Enable only when you want strict enforcement. |
| 209 | |
| 210 | ## Advanced Usage |
| 211 | |
| 212 | ### Multiple Conditions |
| 213 | |
| 214 | Check multiple fields simultaneously: |
| 215 | |
| 216 | ```markdown |
| 217 | --- |
| 218 | name: api-key-in-typescript |
| 219 | enabled: true |
| 220 | event: file |
| 221 | conditions: |
| 222 | - field: file_path |
| 223 | operator: regex_match |
| 224 | pattern: \.tsx?$ |
| 225 | - field: new_text |
| 226 | operator: regex_match |
| 227 | pattern: (API_KEY|SECRET|TOKEN)\s*=\s*["'] |
| 228 | --- |
| 229 | |
| 230 | 🔐 **Hardcoded credential in TypeScript!** |
| 231 | |
| 232 | Use environment variables instead of hardcoded values. |
| 233 | ``` |
| 234 | |
| 235 | ### Operators Reference |
| 236 | |
| 237 | - `regex_match`: Pattern must match (most common) |
| 238 | - `contains`: String must contain pattern |
| 239 | - `equals`: Exact string match |
| 240 | - `not_contains`: String must NOT contain pattern |
| 241 | - `starts_with`: String starts with pattern |
| 242 | - `ends_with`: String ends with pattern |
| 243 | |
| 244 | ### Field Reference |
| 245 | |
| 246 | **For bash events:** |
| 247 | - `command`: The bash command string |
| 248 | |
| 249 | **For file events:** |
| 250 | - `file_path`: Path to file being edited |
| 251 | - `new_text`: New content being added (Edit, Write) |
| 252 | - `old_text`: Old content being replaced (Edit only) |
| 253 | - `content`: File content (Write only) |
| 254 | |
| 255 | **For prompt events:** |
| 256 | - `user_prompt`: The user's submitted prompt text |
| 257 | |
| 258 | **For stop events:** |
| 259 | - Use general matching on session state |
| 260 | |
| 261 | ## Management |
| 262 | |
| 263 | ### Enable/Disable Rules |
| 264 | |
| 265 | **Temporarily disable:** |
| 266 | Edit the `.local.md` file and set `enabled: false` |
| 267 | |
| 268 | **Re-enable:** |
| 269 | Set `enabled: true` |
| 270 | |
| 271 | **Or use interactive tool:** |
| 272 | ``` |
| 273 | /hookify:configure |
| 274 | ``` |
| 275 | |
| 276 | ### Delete Rules |
| 277 | |
| 278 | Simply delete the `.local.md` file: |
| 279 | ```bash |
| 280 | rm .claude/hookify.my-rule.local.md |
| 281 | ``` |
| 282 | |
| 283 | ### View All Rules |
| 284 | |
| 285 | ``` |
| 286 | /hookify:list |
| 287 | ``` |
| 288 | |
| 289 | ## Installation |
| 290 | |
| 291 | This plugin is part of the Claude Code Marketplace. It should be auto-discovered when the marketplace is installed. |
| 292 | |
| 293 | **Manual testing:** |
| 294 | ```bash |
| 295 | cc --plugin-dir /path/to/hookify |
| 296 | ``` |
| 297 | |
| 298 | ## Requirements |
| 299 | |
| 300 | - Python 3.7+ |
| 301 | - No external dependencies (uses stdlib only) |
| 302 | |
| 303 | ## Troubleshooting |
| 304 | |
| 305 | **Rule not triggering:** |
| 306 | 1. Check rule file exists in `.claude/` directory (in project root, not plugin directory) |
| 307 | 2. Verify `enabled: true` in frontmatter |
| 308 | 3. Test regex pattern separately |
| 309 | 4. Rules should work immediately - no restart needed |
| 310 | 5. Try `/hookify:list` to see if rule is loaded |
| 311 | |
| 312 | **Import errors:** |
| 313 | - Ensure Python 3 is available: `python3 --version` |
| 314 | - Check hookify plugin is installed |
| 315 | |
| 316 | **Pattern not matching:** |
| 317 | - Test regex: `python3 -c "import re; print(re.search(r'pattern', 'text'))"` |
| 318 | - Use unquoted patterns in YAML to avoid escaping issues |
| 319 | - Start simple, then add complexity |
| 320 | |
| 321 | **Hook seems slow:** |
| 322 | - Keep patterns simple (avoid complex regex) |
| 323 | - Use specific event types (bash, file) instead of "all" |
| 324 | - Limit number of active rules |
| 325 | |
| 326 | ## Contributing |
| 327 | |
| 328 | Found a useful rule pattern? Consider sharing example files via PR! |
| 329 | |
| 330 | ## Future Enhancements |
| 331 | |
| 332 | - Severity levels (error/warning/info distinctions) |
| 333 | - Rule templates library |
| 334 | - Interactive pattern builder |
| 335 | - Hook testing utilities |
| 336 | - JSON format support (in addition to markdown) |
| 337 | |
| 338 | ## License |
| 339 | |
| 340 | MIT License |