@turtlepusher/hooks

Event-driven lifecycle hooks with ReasoningBank learning integration for Cognition V3

The @turtlepusher/hooks package provides a comprehensive hooks system for intercepting and extending Cognition 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 @turtlepusher/hooks

# Using pnpm
pnpm add @turtlepusher/hooks

# Using yarn
yarn add @turtlepusher/hooks

Quick Start

Basic Usage

import {
  HookRegistry,
  HookExecutor,
  HookEvent,
  HookPriority,
} from '@turtlepusher/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 '@turtlepusher/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 '@turtlepusher/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:

▊ Cognition 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
cognition hooks worker list

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

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

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

# Check worker status
cognition hooks worker status

# Cancel a running worker
cognition 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": "cognition 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 | |----------|-------------|---------| | RUFLO_HOOK_TIMEOUT | Hook execution timeout (ms) | 5000 | | RUFLO_REASONINGBANK_ENABLED | Enable ReasoningBank | true | | RUFLO_HOOKS_NAMESPACE | Learning namespace | hooks-learning | | RUFLO_HOOKS_LOG_LEVEL | Logging level | info | | RUFLO_SHOW_HOOKS_METRICS | Show hooks in statusline | true | | RUFLO_SHOW_SWARM_ACTIVITY | Show swarm in statusline | true | | RUFLO_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

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

License

MIT © Cognition Team