#145 Claude Flow Hooks System - Automated Lifecycle Management with Claude Code Integration · ruflo

Overview

Claude Flow now includes a comprehensive hooks system that integrates seamlessly with Claude Code's lifecycle events. This system enables automated coordination, memory management, and performance optimization throughout your development workflow.

What Are Hooks?

Hooks are automated commands that execute at specific points in Claude Code's lifecycle. They provide deterministic control over Claude Code's behavior without interrupting your workflow.

Key Features

Hook Types Available:

PreToolUse Hooks - Execute BEFORE Claude Code runs a tool:
- Edit/MultiEdit: Validates syntax, assigns agents
- Write: Creates directories, checks permissions
- Bash: Validates command safety
- Task: Optimizes topology, spawns agents
PostToolUse Hooks - Execute AFTER tool completion:
- File Operations: Formats code, updates memory
- Commands: Tracks metrics, stores results
- Tasks: Analyzes performance, updates telemetry
- Searches: Caches results, optimizes patterns
Notification Hooks - Handle system notifications
Stop Hooks - Execute when session ends
SubagentStop Hooks - Execute when agents complete

Installation & Setup

Quick Start

Hooks are automatically configured when you initialize a Claude Flow project:

npx claude-flow init --sparc

This creates a .claude/settings.json file with pre-configured hooks.

Manual Configuration

Add to your .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit < /dev/null | MultiEdit",
        "hooks": [{
          "type": "command",
          "command": "npx claude-flow hooks pre-edit --file \"${CLAUDE_FLOW_FILE}\" --validate-syntax --auto-assign-agents",
          "blocking": false
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [{
          "type": "command",
          "command": "npx claude-flow hooks post-edit --file \"${CLAUDE_FLOW_FILE}\" --format-code --update-memory --train-neural"
        }]
      }
    ]
  }
}

Available Hook Commands

Pre-Task Hook

npx claude-flow hooks pre-task --description "Build API" --task-id task-123 --auto-spawn-agents

Post-Task Hook

npx claude-flow hooks post-task --task-id task-123 --analyze-performance --generate-insights

Pre-Edit Hook

npx claude-flow hooks pre-edit --file "src/api.js" --validate-syntax

Post-Edit Hook

npx claude-flow hooks post-edit --file "src/api.js" --memory-key "swarm/edits/123"

Session-End Hook

npx claude-flow hooks session-end --export-metrics --generate-summary

Environment Variables

Hooks have access to context-specific environment variables:

${CLAUDE_FLOW_FILE} - The file being operated on
${CLAUDE_FLOW_COMMAND} - The bash command being executed
${CLAUDE_FLOW_TASK} - The task description
${CLAUDE_FLOW_TASK_ID} - Unique task identifier
${CLAUDE_FLOW_PATTERN} - Search pattern used
${CLAUDE_FLOW_MESSAGE} - Notification message
${CLAUDE_FLOW_AGENT_ID} - Agent identifier

⚡ Benefits

Automated Workflows: No manual intervention needed
Performance Tracking: Real-time metrics collection
Error Prevention: Validation before operations
Memory Persistence: Context maintained across sessions
Neural Learning: Patterns improve over time
Non-Blocking: Most hooks run in parallel

️ Security & Performance

Blocking vs Non-Blocking: Critical operations (like command validation) can block, while others run in background
Full Permissions: Hooks run with user permissions
Caching: Improves performance over time
Async Operations: Neural training happens asynchronously

Documentation

For detailed documentation, see:

Important Notes

Hooks are enabled by default in new projects
To disable temporarily: export CLAUDE_FLOW_HOOKS_ENABLED=false
Test individual hooks: npx claude-flow hooks pre-edit --file test.js
View hook logs: npx claude-flow logs hooks --tail 50

Use Cases

Auto-format code on save
Validate commands before execution
Auto-spawn agents for complex tasks
Track performance metrics
Persist memory across sessions
Train neural patterns from successful operations

This hooks system represents a major step forward in automated AI-driven development workflows!