# 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

```bash
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:

```markdown
# 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:

```json
{
  "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`:

```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`):

```markdown
# 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:**

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

### Example 2: Post-deployment Notification

**Description file** (`deploy_notify.json`):

```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:**

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

### Example 3: Error Logging

**Description file** (`error_logger.md`):

```markdown
# 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:**

```bash
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:

```markdown
# 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:

```bash
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:

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

### Multiple Hooks

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

```bash
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:

```yaml
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

```bash
# 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

```bash
# 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

```bash
# 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:**
```markdown
# Good
# Command: ./scripts/lint.sh

# Bad
# Command: lint.sh
```

**Set appropriate timeouts:**
```markdown
# Fast operations: 5-10 seconds
# Timeout: 10000

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

**Handle errors gracefully:**
```bash
#!/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:

```markdown
# Specific
# Tool Filter: git

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

### Testing Hooks

Test hooks before enabling:

```markdown
# Enabled: false
```

Then manually test the command, and enable once verified.

## Troubleshooting

### Hook not triggering

**Check event type:**
```bash
# Verify event is correct in .claude/hooks.yaml
cat .claude/hooks.yaml
```

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

### Command fails

**Check command path:**
```bash
# Test command manually
npm run lint

# If fails, fix path or installation
```

**Check timeout:**
```markdown
# 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](../../docs/META_AGENTS.md) - Meta-agent ecosystem
- [ARTIFACT_STANDARDS.md](../../docs/ARTIFACT_STANDARDS.md) - Artifact system
- [hook-description schema](../../schemas/hook-description.json)
- [hook-config schema](../../schemas/hook-config.json)

## 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!