@claude-flow/hooks

@claude-flow/hooks — Registers and runs lifecycle hooks (PreEdit, PostTask, session start and end, and more) in priority order, and feeds their outcomes to ReasoningBank pattern learning.

Supported environments: Node.js 20+ · ESM

Quickstart

npm install @claude-flow/hooks

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

const registry = new HookRegistry();
registry.register(HookEvent.PreEdit, async () => ({ success: true }), HookPriority.Normal, { name: 'log-edit' });
console.log(registry.getForEvent(HookEvent.PreEdit).map((h) => h.name));

Expected output:

[ 'log-edit' ]

Built on @claude-flow/shared; used by @claude-flow/plugins.

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

Hook Priorities

Background Workers

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

Available Workers

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

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

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

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

Built by rUv · ruv.io · Source