@claude-flow/hooks weekly downloads statistics

@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…