441 lines
13 KiB
Markdown
441 lines
13 KiB
Markdown
# @claude-flow/hooks
|
|
|
|
[](https://www.npmjs.com/package/@claude-flow/hooks)
|
|
[](https://www.npmjs.com/package/@claude-flow/hooks)
|
|
[](https://opensource.org/licenses/MIT)
|
|
[](https://www.typescriptlang.org/)
|
|
[](https://nodejs.org/)
|
|
|
|
> 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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.
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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`):
|
|
|
|
```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) - Shared utilities and types
|
|
- [@claude-flow/neural](../neural) - Neural network and SONA learning
|
|
- [@claude-flow/swarm](../swarm) - Multi-agent coordination
|
|
- [@claude-flow/memory](../memory) - AgentDB memory system
|
|
|
|
## License
|
|
|
|
MIT © [Claude Flow Team](https://github.com/ruvnet/claude-flow)
|