Name	Name	Last commit message	Last commit date
parent directory ..
__tests__	__tests__
bin	bin
src	src
README.md	README.md
package.json	package.json
tmp.json	tmp.json
tsconfig.json	tsconfig.json
vitest.config.ts	vitest.config.ts

@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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

@claude-flow/hooks

Features

Installation

Quick Start

Basic Usage

Initialize with Daemons

Using MCP Tools

CLI Commands

Hooks Daemon

Statusline

Hook Events

Hook Priorities

Background Workers

Available Workers

Worker CLI Commands

Performance Targets

UserPromptSubmit Integration

MCP Tools

API Reference

HookRegistry

HookExecutor

DaemonManager

StatuslineGenerator

Environment Variables

Integration with Claude Code

Related Packages

License

FilesExpand file tree

hooks

Directory actions

More options

Directory actions

More options

Latest commit

History

hooks

Folders and files

parent directory

README.md

@claude-flow/hooks

Features

Installation

Quick Start

Basic Usage

Initialize with Daemons

Using MCP Tools

CLI Commands

Hooks Daemon

Statusline

Hook Events

Hook Priorities

Background Workers

Available Workers

Worker CLI Commands

Performance Targets

UserPromptSubmit Integration

MCP Tools

API Reference

HookRegistry

HookExecutor

DaemonManager

StatuslineGenerator

Environment Variables

Integration with Claude Code

Related Packages

License