@claude-flow/hooks

@claude-flow/hooks

Event-driven lifecycle hooks with ReasoningBank learning integration for Claude Flow V3

The @claude-flow/hooks package provides a comprehensive hooks system for intercepting and extending Claude Flow operations. It enables intelligent task routing, pattern learning, background metrics collection, and real-time statusline integration.

Features

• 🎣 Hook Registry - Priority-based hook registration with filtering and management
• ⚡ Hook Executor - Timeout handling, error recovery, and result aggregation
• 🤖 Background Daemons - Metrics collection, swarm monitoring, pattern learning
• 👷 Background Workers - 12 specialized workers for analysis, optimization, and automation
• 📊 Statusline Integration - Real-time status display for Claude Code
• 🧠 ReasoningBank Learning - Intelligent task routing based on learned patterns
• 🔧 MCP Tools - 13 MCP tools for programmatic hooks access
• 🔄 V2 Compatibility - Backward compatible with V2 hook commands

Installation

# Using npm
npm install @claude-flow/hooks

# Using pnpm
pnpm add @claude-flow/hooks

# Using yarn
yarn add @claude-flow/hooks

Quick Start

Basic Usage

import {
  HookRegistry,
  HookExecutor,
  HookEvent,
  HookPriority,
} from '@claude-flow/hooks';

// Create registry and executor
const registry = new HookRegistry();
const executor = new HookExecutor(registry);

// Register a pre-edit hook
registry.register(
  HookEvent.PreEdit,
  async (context) => {
    console.log(`Editing file: ${context.file?.path}`);
    return { success: true };
  },
  HookPriority.Normal,
  { name: 'log-edits' }
);

// Execute hooks
const result = await executor.preEdit('src/app.ts', 'modify');
console.log(`Hooks executed: ${result.hooksExecuted}`);

Initialize with Daemons

import { initializeHooks } from '@claude-flow/hooks';

// Initialize full system with background daemons
const { registry, executor, statusline } = await initializeHooks({
  enableDaemons: true,
  enableStatusline: true,
});

// Generate statusline
console.log(statusline.generateStatusline());

Using MCP Tools

import { hooksMCPTools, getHooksTool } from '@claude-flow/hooks';

// Get specific tool
const routeTool = getHooksTool('hooks/route');

// Execute routing
const result = await routeTool.handler({
  task: 'Implement user authentication',
  includeExplanation: true,
});

console.log(`Recommended agent: ${result.recommendedAgent}`);
console.log(`Confidence: ${result.confidence}%`);

CLI Commands

Hooks Daemon

Manage background daemon processes for metrics and learning.

# Start daemon with default 60s interval
hooks-daemon start

# Start with custom interval (30 seconds)
hooks-daemon start 30

# Stop daemon
hooks-daemon stop

# Check status
hooks-daemon status

# Run pattern consolidation
hooks-daemon consolidate

# Export learned patterns
hooks-daemon export json

# Rebuild HNSW index
hooks-daemon rebuild-index

# Notify activity (for hook integration)
hooks-daemon notify-activity

Statusline

Generate statusline output for Claude Code integration.

# Display formatted statusline
statusline

# Output JSON data
statusline --json

# Compact JSON (single line)
statusline --compact

# Show help
statusline --help

Example Output:

▊ Claude Flow V3 ● agentic-flow@alpha  │  ⎇ v3
─────────────────────────────────────────────────────
🏗️  DDD Domains    [●●●●●]  5/5    ⚡ 1.0x → 2.49x-7.47x
🤖 Swarm Agents    ◉ [ 5/15]      🟢 CVE 3/3    💾 156 patterns
🔧 Architecture    DDD ●93%  │  Security ●CLEAN  │  Hooks ●ACTIVE
📊 Routing         89% accuracy │  Avg 4.2ms │  1547 operations
─────────────────────────────────────────────────────

Hook Events

Event	Description
PreToolUse	Before any tool execution
PostToolUse	After tool execution completes
PreEdit	Before file modification
PostEdit	After file modification
PreRead	Before file read
PostRead	After file read
PreCommand	Before shell command execution
PostCommand	After shell command completes
PreTask	Before task starts
PostTask	After task completes
TaskProgress	During task execution
SessionStart	When session begins
SessionEnd	When session ends
SessionRestore	When restoring previous session
AgentSpawn	When agent is spawned
AgentTerminate	When agent terminates
PreRoute	Before task routing
PostRoute	After routing decision
PatternLearned	When new pattern is learned
PatternConsolidated	When patterns are consolidated

Hook Priorities

Priority	Value	Use Case
Critical	1000	Security validation, must run first
High	100	Pre-processing, preparation
Normal	50	Standard hooks
Low	10	Logging, metrics
Background	1	Async operations, runs last

Background Workers

The hooks system includes 12 specialized background workers that can be triggered automatically or manually dispatched.

Available Workers

Worker	Priority	Est. Time	Description
ultralearn	normal	60s	Deep knowledge acquisition and learning
optimize	high	30s	Performance optimization and tuning
consolidate	low	20s	Memory consolidation and cleanup
predict	normal	15s	Predictive preloading and anticipation
audit	critical	45s	Security analysis and vulnerability scanning
map	normal	30s	Codebase mapping and architecture analysis
preload	low	10s	Resource preloading and cache warming
deepdive	normal	60s	Deep code analysis and examination
document	normal	45s	Auto-documentation generation
refactor	normal	30s	Code refactoring suggestions
benchmark	normal	60s	Performance benchmarking
testgaps	normal	30s	Test coverage analysis

Worker CLI Commands

# List all available workers
claude-flow hooks worker list

# Detect triggers from prompt text
claude-flow hooks worker detect --prompt "optimize performance"

# Auto-dispatch when triggers match (confidence ≥0.6)
claude-flow hooks worker detect --prompt "deep dive into auth" --auto-dispatch --min-confidence 0.6

# Manually dispatch a worker
claude-flow hooks worker dispatch --trigger refactor --context "auth module"

# Check worker status
claude-flow hooks worker status

# Cancel a running worker
claude-flow hooks worker cancel --id worker_refactor_1_abc123

Performance Targets

Metric	Target
Trigger detection	<5ms
Worker spawn	<50ms
Max concurrent	10

UserPromptSubmit Integration

Workers are automatically triggered via the UserPromptSubmit hook when prompt patterns match worker triggers with confidence ≥0.6. Add this to your Claude settings:

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": ".*",
      "hooks": [{
        "type": "command",
        "timeout": 6000,
        "command": "claude-flow hooks worker detect --prompt \"$USER_PROMPT\" --auto-dispatch --min-confidence 0.6"
      }]
    }]
  }
}

MCP Tools

Tool	Description
hooks/pre-edit	Get context and suggestions before file edit
hooks/post-edit	Record edit outcome for learning
hooks/route	Route task to optimal agent
hooks/metrics	Query learning metrics
hooks/pre-command	Assess command risk
hooks/post-command	Record command outcome
hooks/daemon-status	Get daemon status
hooks/statusline	Get statusline data
hooks/worker-list	List all 12 background workers
hooks/worker-dispatch	Dispatch a worker by trigger type
hooks/worker-status	Get status of running workers
hooks/worker-detect	Detect worker triggers from prompt text
hooks/worker-cancel	Cancel a running worker

API Reference

HookRegistry

class HookRegistry {
  // Register a hook
  register(
    event: HookEvent,
    handler: HookHandler,
    priority: HookPriority,
    options?: HookRegistrationOptions
  ): string;

  // Unregister a hook
  unregister(hookId: string): boolean;

  // Get hooks for event
  getForEvent(event: HookEvent, enabledOnly?: boolean): HookEntry[];

  // Enable/disable hooks
  enable(hookId: string): boolean;
  disable(hookId: string): boolean;

  // List hooks with filtering
  list(filter?: HookListFilter): HookEntry[];

  // Get statistics
  getStats(): HookRegistryStats;
}

HookExecutor

class HookExecutor {
  // Execute hooks for any event
  execute<T>(
    event: HookEvent,
    context: Partial<HookContext<T>>,
    options?: HookExecutionOptions
  ): Promise<HookExecutionResult>;

  // Convenience methods
  preToolUse(toolName: string, parameters: Record<string, unknown>): Promise<HookExecutionResult>;
  postToolUse(toolName: string, parameters: Record<string, unknown>, duration: number): Promise<HookExecutionResult>;
  preEdit(filePath: string, operation: 'create' | 'modify' | 'delete'): Promise<HookExecutionResult>;
  postEdit(filePath: string, operation: 'create' | 'modify' | 'delete', duration: number): Promise<HookExecutionResult>;
  preCommand(command: string, workingDirectory?: string): Promise<HookExecutionResult>;
  postCommand(command: string, exitCode: number, output?: string, error?: string): Promise<HookExecutionResult>;
  sessionStart(sessionId: string): Promise<HookExecutionResult>;
  sessionEnd(sessionId: string): Promise<HookExecutionResult>;
  agentSpawn(agentId: string, agentType: string): Promise<HookExecutionResult>;
  agentTerminate(agentId: string, agentType: string, status: string): Promise<HookExecutionResult>;
}

DaemonManager

class DaemonManager {
  // Register and manage daemons
  register(config: DaemonConfig, task: () => Promise<void>): void;
  start(name: string): Promise<void>;
  stop(name: string): Promise<void>;
  restart(name: string): Promise<void>;

  // Bulk operations
  startAll(): Promise<void>;
  stopAll(): Promise<void>;

  // Status
  getState(name: string): DaemonState | undefined;
  getAllStates(): DaemonState[];
  isRunning(name: string): boolean;
}

StatuslineGenerator

class StatuslineGenerator {
  // Register data sources
  registerDataSources(sources: StatuslineDataSources): void;

  // Generate output
  generateData(): StatuslineData;
  generateStatusline(): string;
  generateJSON(): string;
  generateCompactJSON(): string;

  // Configuration
  updateConfig(config: Partial<StatuslineConfig>): void;
  invalidateCache(): void;
}

Environment Variables

Variable	Description	Default
CLAUDE_FLOW_HOOK_TIMEOUT	Hook execution timeout (ms)	5000
CLAUDE_FLOW_REASONINGBANK_ENABLED	Enable ReasoningBank	true
CLAUDE_FLOW_HOOKS_NAMESPACE	Learning namespace	hooks-learning
CLAUDE_FLOW_HOOKS_LOG_LEVEL	Logging level	info
CLAUDE_FLOW_SHOW_HOOKS_METRICS	Show hooks in statusline	true
CLAUDE_FLOW_SHOW_SWARM_ACTIVITY	Show swarm in statusline	true
CLAUDE_FLOW_SHOW_PERFORMANCE	Show performance targets	true

Integration with Claude Code

Add to your Claude settings (~/.claude/settings.json):

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "timeout": 5000,
        "command": "hooks-daemon start"
      }]
    }],
    "SessionEnd": [{
      "hooks": [{
        "type": "command",
        "timeout": 3000,
        "command": "hooks-daemon stop"
      }]
    }],
    "PreToolUse": [{
      "hooks": [{
        "type": "command",
        "timeout": 100,
        "command": "hooks-daemon notify-activity"
      }]
    }]
  },
  "statusLine": {
    "type": "command",
    "command": "statusline"
  }
}

Related Packages

• @claude-flow/shared - Shared utilities and types
• @claude-flow/neural - Neural network and SONA learning
• @claude-flow/swarm - Multi-agent coordination
• @claude-flow/memory - AgentDB memory system

License

MIT © Claude Flow Team