Mastering Hooks

mastering-hooks

Contents

• Overview
• Decision Tree
• Capabilities
• When NOT to Use
• References

Overview

RuleZ is a high-performance AI policy engine that intercepts AI coding assistant events and executes configured actions. It works across multiple platforms through adapter-based event translation.

User Prompt --> AI Assistant --> RuleZ Binary --> [Match Rules] --> Execute Actions
                    |                                 |
                    v                                 v
              PreToolUse                       inject/run/block
              PostToolUse                      context/validation
              BeforeAgent
              PermissionRequest

Supported platforms:

• Claude Code (native) - Full event support
• Gemini CLI - Via adapter with dual-fire events
• GitHub Copilot - Via adapter
• OpenCode - Via adapter with dual-fire events

System components:

• RuleZ Binary (Rust): Fast, deterministic hook execution at runtime
• hooks.yaml: Declarative configuration defining rules, matchers, and actions
• Platform Adapters: Translate platform-specific events to unified RuleZ event types
• This Skill: Intelligent assistant for setup, debugging, and optimization

Decision Tree

What do you need?
|
+-- New to RuleZ? --> [1. Install & Initialize]
|
+-- Have hooks.yaml but hooks not working? --> [4. Troubleshoot]
|
+-- Need to add new behavior? --> [2. Create Rules]
|
+-- Want to understand existing config? --> [3. Explain Configuration]
|
+-- Performance or complexity issues? --> [5. Optimize]
|
+-- Setting up for Gemini/Copilot/OpenCode? --> [6. Multi-Platform Setup]

Capabilities

1. Install & Initialize RuleZ

Use when: Setting up RuleZ for the first time in a project or user-wide.

Checklist:

1. Verify RuleZ binary is installed: rulez --version --json
2. Initialize configuration: rulez init (creates .claude/hooks.yaml)
3. Register with Claude Code: rulez install --project or rulez install --user
4. Validate configuration: rulez validate
5. Verify installation: Check .claude/settings.json for hook entries

Expected output from rulez --version --json:

{"version": "1.8.0", "api_version": "1.8.0", "git_sha": "abc1234"}

Reference: cli-commands.md

2. Create Hook Rules

Use when: Adding new behaviors like context injection, command validation, or workflow automation.

Checklist:

1. Identify the event type (PreToolUse, PostToolUse, BeforeAgent, etc.)
2. Define matchers (tools, extensions, directories, patterns)
3. Choose action type (inject, run, block, require_fields)
4. Write the rule in hooks.yaml
5. Validate: rulez validate
6. Test with: rulez debug <event> --tool <tool_name>

Rule anatomy:

hooks:
  - name: rule-name           # kebab-case identifier
    event: PreToolUse         # When to trigger
    match:
      tools: [Write, Edit]    # What to match
      extensions: [.py]       # Optional: file filters
    action:
      type: inject            # What to do
      source: file            # file | inline | command
      path: .claude/context/python-standards.md

Reference: hooks-yaml-schema.md | rule-patterns.md

3. Explain Configuration

Use when: Understanding what existing hooks do, why they exist, or how they interact.

Checklist:

1. Run rulez explain rule <rule-name> for specific rule analysis
2. Run rulez explain config for full configuration overview
3. Check rule precedence (first match wins within same event)
4. Identify potential conflicts or overlaps

Example output from rulez explain rule python-standards:

Rule: python-standards
Event: PreToolUse
Triggers when: Write or Edit tool used on .py files
Action: Injects content from .claude/context/python-standards.md

Reference: cli-commands.md

4. Troubleshoot Hook Issues

Use when: Hooks not firing, unexpected behavior, or error messages.

Diagnostic checklist:

1. Validate config: rulez validate - catches YAML/schema errors
2. Check registration: cat .claude/settings.json | grep hooks
3. Enable debug logging: rulez debug PreToolUse --tool Write --verbose
4. Check logs: rulez logs --tail 20
5. Verify file paths: Ensure all path: references exist

Common issues:

Reference: troubleshooting-guide.md

5. Optimize Configuration

Use when: Too many rules, slow execution, or complex maintenance.

Optimization checklist:

1. Consolidate overlapping rules with broader matchers
2. Use enabled_when for conditional rules instead of duplicates
3. Move shared context to reusable markdown files
4. Order rules by frequency (most common first)
5. Use block early to short-circuit unnecessary processing

Reference: rule-patterns.md

6. Multi-Platform Setup

Use when: Configuring RuleZ to work with Gemini CLI, GitHub Copilot, or OpenCode in addition to Claude Code.

Key concepts:

• RuleZ uses platform adapters to translate each platform's native events into unified RuleZ event types
• Write rules using RuleZ event types (e.g., PreToolUse) — adapters handle translation automatically
• Some platforms fire dual events (e.g., Gemini's BeforeAgent fires both BeforeAgent and UserPromptSubmit)

Checklist:

1. Install RuleZ: rulez install --project
2. Write rules using standard RuleZ event types
3. Test with rulez debug <event> to verify matching
4. Review platform-adapters.md for platform-specific event mappings

Reference: platform-adapters.md

When NOT to Use This Skill

• Simple Claude Code configuration: Use settings.json directly for basic permissions
• One-time context injection: Just paste into your prompt
• Dynamic runtime decisions: RuleZ is deterministic; use MCP servers for complex logic

References

Example: Complete hooks.yaml

# .claude/hooks.yaml
version: "1"

hooks:
  # Inject Python standards before writing Python files
  - name: python-standards
    event: PreToolUse
    match:
      tools: [Write, Edit]
      extensions: [.py]
    action:
      type: inject
      source: file
      path: .claude/context/python-standards.md

  # Block dangerous git commands
  - name: block-force-push
    event: PreToolUse
    match:
      tools: [Bash]
      command_match: "git push.*--force"
    action:
      type: block
      reason: "Force push requires explicit approval."

  # Run security check before committing
  - name: pre-commit-security
    event: PreToolUse
    match:
      tools: [Bash]
      command_match: "git commit"
    action:
      type: run
      command: .claude/validators/check-secrets.sh
      timeout: 30

  # Track agent activity (works on Claude Code and Gemini)
  - name: log-agent-start
    event: BeforeAgent
    match: {}
    action:
      type: inject
      source: inline
      content: |
        **Agent Policy**: Follow project conventions in CLAUDE.md.