Write Hookify Rules

What a Rule Does

A Hookify rule checks an action for a text pattern. When the pattern matches, the rule shows a message or blocks the action.

Store each rule in this path:

.claude/hookify.{rule-name}.local.md

Keep the rule name short and clear.

Basic Rule

---
name: warn-force-delete
enabled: true
event: bash
action: warn
pattern: rm\s+-rf
---

This command can delete many files. Check the path before you run it.

The message after the frontmatter is shown when the rule runs.

Frontmatter Fields

Use either pattern or conditions. Do not use both unless your Hookify version says this is allowed.

Events

bash

Checks a shell command.

Useful patterns:

rm\s+-rf
dd\s+if=
mkfs
sudo\s+
su\s+
chmod\s+777

Match the command itself. Do not match the command output.

file

Checks a file change.

Useful patterns:

console\.log\(
debugger
eval\(
innerHTML\s*=
\.env$
credentials
\.pem$

A file rule may check the file path, old text, new text, or full content.

stop

Runs when Claude is about to stop.

Use this to remind Claude about tests, checks, or other final work. The pattern .* matches any text, including empty text in many regular expression tools. If your Hookify version does not run the rule for empty text, use a condition or test the rule first.

prompt

Checks the user's prompt.

Use this for work rules, such as requiring a plan for a large change. Keep prompt rules narrow. A wide pattern may run on tasks that do not need it.

all

Checks all supported events.

Use all only when the same rule makes sense for every event. Event data is not always the same, so test the rule for each event.

Rules With More Than One Condition

Use conditions when every check must pass.

---
name: warn-env-api-keys
enabled: true
event: file
action: warn
conditions:
  - field: file_path
    operator: regex_match
    pattern: '\.env$'
  - field: new_text
    operator: contains
    pattern: API_KEY
---

You are adding an API key to an .env file. Make sure the file is in .gitignore.

All conditions must match for the rule to run.

Fields by Event

Do not use a field from the wrong event. For example, command does not work with a file event.

Operators

These checks may be case-sensitive. Add both forms or use a case-free regular expression when needed.

Write Safe Patterns

A regular expression is a text pattern.

Common parts:

Avoid Wide Matches

This pattern is too wide:

log

It also matches words such as login and dialog.

Use a clear pattern:

console\.log\(

Allow Small Command Changes

This pattern is too exact:

rm -rf /tmp

This pattern allows one or more blank characters:

rm\s+-rf

Think about flags in a different order, quoted paths, full command paths, and line breaks. One pattern may not catch every form.

Quote YAML With Care

Plain patterns often work:

pattern: rm\s+-rf

Single quotes are safer when YAML may treat a character as special:

pattern: '\.env$'

Inside single quotes, keep backslashes as written. Do not add a second backslash.

If the pattern contains a single quote, write two single quotes inside the YAML string:

pattern: 'user''s file'

Test Before Use

Test the pattern against text that should match:

python3 -c "import re; print(bool(re.search(r'rm\s+-rf', 'rm   -rf build')))"

Also test text that should not match:

python3 -c "import re; print(bool(re.search(r'rm\s+-rf', 'rm -r build')))"

The first test should print True. The second should print False.

Test the full rule in a safe place before using action: block. Start with action: warn when you are not sure.

Concrete Example

The user asks:

Warn me when I add console.log to a JavaScript file.

Create this file:

.claude/hookify.warn-console-log.local.md

Use this content:

---
name: warn-console-log
enabled: true
event: file
action: warn
conditions:
  - field: file_path
    operator: regex_match
    pattern: '\.(js|jsx|ts|tsx)$'
  - field: new_text
    operator: regex_match
    pattern: 'console\.log\s*\('
---

You added console.log to a JavaScript or TypeScript file. Remove it if it is only for debug work.

This rule checks both the file name and the new text. It will not run for a Python file.

File Setup

• Put rules in the project root .claude/ folder.
• Name files .claude/hookify.{clear-name}.local.md.
• Give each rule a unique name.
• Add .claude/*.local.md to .gitignore if rules should stay local.
• Do not put keys, passwords, or private data in a rule or its message.
• Set enabled: false to turn off a rule without deleting it.
• Use warn for advice. Use block only when the action must not run.

Commands

/hookify [description]

Creates a rule. With no text, it may use the current chat as the source.

/hookify-list

Shows all rules.

/hookify-configure

Turns rules on or off.

/hookify-help

Shows the full Hookify help.

Smallest Valid Rule

---
name: warn-dangerous-command
enabled: true
event: bash
pattern: dangerous_command
---

This command may be unsafe. Check it before you run it.