gh-epieczko-betty/agents/meta.hook/README.md

meta.hook - Hook Creator Meta-Agent

Generates Claude Code hooks from natural language descriptions.

Overview

meta.hook is a meta-agent that creates Claude Code hooks from simple description files. It generates hook configurations that execute commands in response to events like tool calls, errors, or user interactions.

What it does:

• Parses hook descriptions (Markdown or JSON)
• Generates .claude/hooks.yaml configurations
• Validates event types and hook structure
• Manages hook lifecycle (create, update, enable/disable)
• Supports tool-specific filtering

Quick Start

Create a Hook

python3 agents/meta.hook/meta_hook.py examples/my_hook.md

Output:

🪝  meta.hook - Creating hook from examples/my_hook.md

✨ Hook 'pre-commit-lint' created successfully!

📄 Created/updated file:
   - .claude/hooks.yaml

✅ Hook 'pre-commit-lint' is ready to use
   Event: before-tool-call
   Command: npm run lint

Hook Description Format

Create a Markdown file:

# Name: pre-commit-lint

# Event: before-tool-call

# Tool Filter: git

# Description: Run linter before git commits

# Command: npm run lint

# Timeout: 30000

# Enabled: true

Or use JSON format:

{
  "name": "pre-commit-lint",
  "event": "before-tool-call",
  "tool_filter": "git",
  "description": "Run linter before git commits",
  "command": "npm run lint",
  "timeout": 30000,
  "enabled": true
}

Event Types

Supported Claude Code events:

• before-tool-call - Before any tool is executed
• after-tool-call - After any tool completes
• on-error - When a tool call fails
• user-prompt-submit - When user submits a prompt
• assistant-response - After assistant responds

Generated Structure

meta.hook generates or updates .claude/hooks.yaml:

hooks:
- name: pre-commit-lint
  event: before-tool-call
  command: npm run lint
  description: Run linter before git commits
  enabled: true
  tool_filter: git
  timeout: 30000

Usage Examples

Example 1: Pre-commit Linting

Description file (lint_hook.md):

# Name: pre-commit-lint

# Event: before-tool-call

# Tool Filter: git

# Description: Run linter before git commits to ensure code quality

# Command: npm run lint

# Timeout: 30000

Create hook:

python3 agents/meta.hook/meta_hook.py lint_hook.md

Example 2: Post-deployment Notification

Description file (deploy_notify.json):

{
  "name": "deploy-notify",
  "event": "after-tool-call",
  "tool_filter": "deploy",
  "description": "Send notification after deployment",
  "command": "./scripts/notify-team.sh",
  "timeout": 10000
}

Create hook:

python3 agents/meta.hook/meta_hook.py deploy_notify.json

Example 3: Error Logging

Description file (error_logger.md):

# Name: error-logger

# Event: on-error

# Description: Log errors to monitoring system

# Command: ./scripts/log-error.sh "{error}" "{tool}"

# Timeout: 5000

# Enabled: true

Create hook:

python3 agents/meta.hook/meta_hook.py error_logger.md

Hook Parameters

Required

• name - Unique hook identifier
• event - Trigger event type
• command - Shell command to execute

Optional

• description - What the hook does
• tool_filter - Only trigger for specific tools (e.g., "git", "npm", "docker")
• enabled - Whether hook is active (default: true)
• timeout - Command timeout in milliseconds (default: none)

Tool Filters

Restrict hooks to specific tools:

# Tool Filter: git

This hook only triggers for git-related tool calls.

Common tool filters:

• git - Git operations
• npm - NPM commands
• docker - Docker commands
• python - Python execution
• bash - Shell commands

Managing Hooks

Update Existing Hook

Run meta.hook with the same hook name to update:

python3 agents/meta.hook/meta_hook.py updated_hook.md

Output:

⚠️  Warning: Hook 'pre-commit-lint' already exists, updating...
✨ Hook 'pre-commit-lint' created successfully!

Disable Hook

Set Enabled: false in description:

# Name: my-hook
# Event: before-tool-call
# Command: echo "test"
# Enabled: false

Multiple Hooks

Create multiple hook descriptions and run meta.hook for each:

for hook in hooks/*.md; do
    python3 agents/meta.hook/meta_hook.py "$hook"
done

Integration

With Claude Code

Hooks are automatically loaded by Claude Code from .claude/hooks.yaml.

With meta.agent

Create agents that use hooks:

name: ci.agent
description: Continuous integration agent
# Hooks will trigger during agent execution

Artifact Types

Consumes

• hook-description - Natural language hook requirements
  • Pattern: **/hook_description.md
  • Format: Markdown or JSON

Produces

• hook-config - Claude Code hook configuration
  • Pattern: .claude/hooks.yaml
  • Schema: schemas/hook-config.json

Common Workflows

Workflow 1: Create and Test Hook

# 1. Create hook description
cat > my_hook.md <<EOF
# Name: test-runner
# Event: after-tool-call
# Tool Filter: git
# Description: Run tests after git push
# Command: npm test
EOF

# 2. Generate hook
python3 agents/meta.hook/meta_hook.py my_hook.md

# 3. Test hook (trigger the event)
git add .
git commit -m "test"

Workflow 2: Create Pre-commit Workflow

# Create linting hook
cat > lint_hook.md <<EOF
# Name: lint
# Event: before-tool-call
# Tool Filter: git
# Command: npm run lint
EOF

python3 agents/meta.hook/meta_hook.py lint_hook.md

# Create test hook
cat > test_hook.md <<EOF
# Name: test
# Event: before-tool-call
# Tool Filter: git
# Command: npm test
EOF

python3 agents/meta.hook/meta_hook.py test_hook.md

Workflow 3: Error Monitoring

# Create error notification hook
cat > error_notify.md <<EOF
# Name: error-notify
# Event: on-error
# Description: Send error notifications
# Command: ./scripts/notify.sh
# Timeout: 5000
EOF

python3 agents/meta.hook/meta_hook.py error_notify.md

Tips & Best Practices

Command Design

Use absolute paths for scripts:

# Good
# Command: ./scripts/lint.sh

# Bad
# Command: lint.sh

Set appropriate timeouts:

# Fast operations: 5-10 seconds
# Timeout: 10000

# Longer operations: 30-60 seconds
# Timeout: 60000

Handle errors gracefully:

#!/bin/bash
# In your hook script
set -e  # Exit on error
trap 'echo "Hook failed"' ERR

Tool Filters

Be specific with tool filters to avoid unnecessary executions:

# Specific
# Tool Filter: git

# Too broad
# (no tool filter - runs for ALL tools)

Testing Hooks

Test hooks before enabling:

# Enabled: false

Then manually test the command, and enable once verified.

Troubleshooting

Hook not triggering

Check event type:

# Verify event is correct in .claude/hooks.yaml
cat .claude/hooks.yaml

Check tool filter:

# If using tool filter, ensure it matches the tool being called
# Tool Filter: git

Command fails

Check command path:

# Test command manually
npm run lint

# If fails, fix path or installation

Check timeout:

# Increase timeout for slow commands
# Timeout: 60000

Hook already exists warning

This is normal when updating hooks. The old version is replaced with the new one.

Architecture

meta.hook
    ├─ Input: hook-description (Markdown/JSON)
    ├─ Parser: extract name, event, command, filters
    ├─ Generator: create/update hooks.yaml
    ├─ Validator: check event types and structure
    └─ Output: .claude/hooks.yaml configuration

Related Documentation

• META_AGENTS.md - Meta-agent ecosystem
• ARTIFACT_STANDARDS.md - Artifact system
• hook-description schema
• hook-config schema

How Claude Uses This

Claude can:

1. Create hooks on demand - "Create a pre-commit linting hook"
2. Automate workflows - "Add error logging for all failures"
3. Build CI/CD pipelines - "Create hooks for test, lint, and deploy"
4. Monitor executions - "Add notification hooks for important events"

meta.hook enables powerful event-driven automation in Claude Code!