Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

checkpoint: File edit:

rUva1332c0935ce
diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json
new file mode 100644
index 0000000000..d5371f4571
--- /dev/null
+++ b/plugin/.claude-plugin/plugin.json
@@ -0,0 +1,45 @@
+{
+ "name": "claude-flow",
+ "description": "Multi-agent swarm coordination, memory management, SPARC methodology, and intelligent hooks for Claude Code. Provides 60+ skills, 100+ commands, and 80+ specialized agents.",
+ "version": "3.0.0",
+ "author": {
+ "name": "ruvnet",
+ "url": "https://github.com/ruvnet"
+ },
+ "homepage": "https://github.com/ruvnet/claude-flow",
+ "repository": "https://github.com/ruvnet/claude-flow",
+ "license": "MIT",
+ "keywords": [
+ "swarm",
+ "multi-agent",
+ "coordination",
+ "memory",
+ "hooks",
+ "sparc",
+ "mcp",
+ "ai-agents"
+ ],
+ "categories": [
+ "Development",
+ "Productivity",
+ "AI Agents",
+ "Workflow Automation"
+ ],
+ "engines": {
+ "claude-code": ">=1.0.0"
+ },
+ "capabilities": {
+ "skills": true,
+ "commands": true,
+ "agents": true,
+ "hooks": true,
+ "mcpServers": true
+ },
+ "main": {
+ "skills": "./skills",
+ "commands": "./commands",
+ "agents": "./agents",
+ "hooks": "./hooks/hooks.json",
+ "mcp": "./.mcp.json"
+ }
+}
diff --git a/plugin/agents b/plugin/agents
new file mode 120000
index 0000000000..590114992a
--- /dev/null
+++ b/plugin/agents
@@ -0,0 +1 @@
+../v2/.claude/agents
\ No newline at end of file
diff --git a/plugin/commands b/plugin/commands
new file mode 120000
index 0000000000..0b631dd5b7
--- /dev/null
+++ b/plugin/commands
@@ -0,0 +1 @@
+../.claude/commands
\ No newline at end of file
diff --git a/plugin/hooks/hooks.json b/plugin/hooks/hooks.json
new file mode 100644
index 0000000000..d9a9f0c01b
--- /dev/null
+++ b/plugin/hooks/hooks.json
@@ -0,0 +1,223 @@
+{
+ "$schema": "https://code.claude.com/schemas/hooks.json",
+ "description": "Claude Flow hooks configuration - Maps to official Claude Code hook events",
+ "hooks": {
+ "PreToolUse": [
+ {
+ "matcher": "^(Write|Edit|MultiEdit)$",
+ "description": "Pre-edit hook for file modifications",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "npx claude-flow@alpha hooks pre-edit --file \"$TOOL_INPUT_file_path\"",
+ "timeout": 5000,
+ "continueOnError": true
+ }
+ ]
+ },
+ {
+ "matcher": "^Bash$",
+ "description": "Pre-command hook for bash execution",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "npx claude-flow@alpha hooks pre-command --command \"$TOOL_INPUT_command\"",
+ "timeout": 3000,
+ "continueOnError": true
+ }
+ ]
+ },
+ {
+ "matcher": "^Task$",
+ "description": "Pre-task hook for agent spawning",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "npx claude-flow@alpha hooks pre-task --description \"$TOOL_INPUT_prompt\"",
+ "timeout": 5000,
+ "continueOnError": true
+ }
+ ]
+ },
+ {
+ "matcher": "^(Grep|Glob|Read)$",
+ "description": "Pre-search hook for caching",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "npx claude-flow@alpha hooks pre-search --query \"$TOOL_INPUT_pattern\"",
+ "timeout": 2000,
+ "continueOnError": true
+ }
+ ]
+ },
+ {
+ "matcher": "^mcp__claude-flow__.*$",
+ "description": "Pre-MCP hook for swarm coordination",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "npx claude-flow@alpha hooks mcp-pre --tool \"$TOOL_NAME\"",
+ "timeout": 3000,
+ "continueOnError": true
+ }
+ ]
+ }
+ ],
+ "PostToolUse": [
+ {
+ "matcher": "^(Write|Edit|MultiEdit)$",
+ "description": "Post-edit hook for formatting and learning",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "npx claude-flow@alpha hooks post-edit --file \"$TOOL_INPUT_file_path\" --success \"$TOOL_SUCCESS\" --train-patterns",
+ "timeout": 5000,
+ "continueOnError": true
+ }
+ ]
+ },
+ {
+ "matcher": "^Bash$",
+ "description": "Post-command hook for metrics",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "npx claude-flow@alpha hooks post-command --command \"$TOOL_INPUT_command\" --success \"$TOOL_SUCCESS\" --exit-code \"$TOOL_EXIT_CODE\"",
+ "timeout": 3000,
+ "continueOnError": true
+ }
+ ]
+ },
+ {
+ "matcher": "^Task$",
+ "description": "Post-task hook for performance analysis",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "npx claude-flow@alpha hooks post-task --task-id \"$TOOL_RESULT_agent_id\" --success \"$TOOL_SUCCESS\" --analyze-performance",
+ "timeout": 5000,
+ "continueOnError": true
+ }
+ ]
+ },
+ {
+ "matcher": "^(Grep|Glob|Read)$",
+ "description": "Post-search hook for caching results",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "npx claude-flow@alpha hooks post-search --query \"$TOOL_INPUT_pattern\" --cache-results",
+ "timeout": 2000,
+ "continueOnError": true
+ }
+ ]
+ },
+ {
+ "matcher": "^mcp__claude-flow__.*$",
+ "description": "Post-MCP hook for coordination state",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "npx claude-flow@alpha hooks mcp-post --tool \"$TOOL_NAME\" --success \"$TOOL_SUCCESS\"",
+ "timeout": 3000,
+ "continueOnError": true
+ }
+ ]
+ }
+ ],
+ "UserPromptSubmit": [
+ {
+ "description": "Route tasks to optimal agents",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "npx claude-flow@alpha hooks route --task \"$PROMPT\" --include-explanation",
+ "timeout": 5000,
+ "continueOnError": true
+ }
+ ]
+ }
+ ],
+ "SessionStart": [
+ {
+ "description": "Initialize session and restore context",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "npx claude-flow@alpha hooks session-start --session-id \"$SESSION_ID\" --load-context",
+ "timeout": 10000,
+ "continueOnError": true
+ }
+ ]
+ }
+ ],
+ "Stop": [
+ {
+ "description": "Evaluate if task is complete",
+ "hooks": [
+ {
+ "type": "prompt",
+ "prompt": "Evaluate if the current task has been completed successfully. Consider: 1) Were all requested changes made? 2) Did tests pass? 3) Is there follow-up work needed? Respond with {\"decision\": \"stop\"} if complete, or {\"decision\": \"continue\", \"reason\": \"...\"} if more work is needed."
+ }
+ ]
+ }
+ ],
+ "SubagentStop": [
+ {
+ "description": "Evaluate if subagent task is complete",
+ "hooks": [
+ {
+ "type": "prompt",
+ "prompt": "Evaluate if the subagent has completed its assigned task. Check if the work output meets the requirements. Respond with {\"decision\": \"stop\"} if complete, or {\"decision\": \"continue\", \"reason\": \"...\"} if more work is needed."
+ }
+ ]
+ }
+ ],
+ "Notification": [
+ {
+ "description": "Handle notifications with swarm status",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "npx claude-flow@alpha hooks notify --message \"$NOTIFICATION_MESSAGE\" --swarm-status",
+ "timeout": 3000,
+ "continueOnError": true
+ }
+ ]
+ }
+ ],
+ "PermissionRequest": [
+ {
+ "matcher": "^mcp__claude-flow__.*$",
+ "description": "Auto-allow claude-flow MCP tools",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "echo '{\"decision\": \"allow\", \"reason\": \"claude-flow MCP tool auto-approved\"}'",
+ "timeout": 1000
+ }
+ ]
+ }
+ ]
+ },
+ "v3HookMapping": {
+ "_comment": "Maps V3 internal hook events to official Claude Code hooks",
+ "PreToolUse": "PreToolUse",
+ "PostToolUse": "PostToolUse",
+ "PreEdit": "PreToolUse (matcher: Edit|Write)",
+ "PostEdit": "PostToolUse (matcher: Edit|Write)",
+ "PreCommand": "PreToolUse (matcher: Bash)",
+ "PostCommand": "PostToolUse (matcher: Bash)",
+ "PreTask": "UserPromptSubmit",
+ "PostTask": "PostToolUse (matcher: Task)",
+ "SessionStart": "SessionStart",
+ "SessionEnd": "Stop",
+ "AgentSpawn": "PostToolUse (matcher: Task)",
+ "AgentTerminate": "SubagentStop",
+ "PreRoute": "UserPromptSubmit",
+ "PostRoute": "PostToolUse",
+ "PatternLearned": "PostToolUse (internal)",
+ "PatternConsolidated": "Stop (internal)"
+ }
+}
diff --git a/plugin/skills b/plugin/skills
new file mode 120000
index 0000000000..454b8427cd
--- /dev/null
+++ b/plugin/skills
@@ -0,0 +1 @@
+../.claude/skills
\ No newline at end of file
diff --git a/v3/@claude-flow/cli/src/init/types.ts b/v3/@claude-flow/cli/src/init/types.ts
new file mode 100644
index 0000000000..6bbb7336d0
--- /dev/null
+++ b/v3/@claude-flow/cli/src/init/types.ts
@@ -0,0 +1,379 @@
+/**
+ * V3 Init System Types
+ * Configuration options for initializing Claude Code integration
+ */
+
+/**
+ * Components that can be initialized
+ */
+export interface InitComponents {
+ /** Create .claude/settings.json with hooks */
+ settings: boolean;
+ /** Copy skills to .claude/skills/ */
+ skills: boolean;
+ /** Copy commands to .claude/commands/ */
+ commands: boolean;
+ /** Copy agents to .claude/agents/ */
+ agents: boolean;
+ /** Create helper scripts in .claude/helpers/ */
+ helpers: boolean;
+ /** Configure statusline */
+ statusline: boolean;
+ /** Create MCP configuration */
+ mcp: boolean;
+ /** Create .claude-flow/ directory (V3 runtime) */
+ runtime: boolean;
+}
+
+/**
+ * Hook configuration options
+ */
+export interface HooksConfig {
+ /** Enable PreToolUse hooks */
+ preToolUse: boolean;
+ /** Enable PostToolUse hooks */
+ postToolUse: boolean;
+ /** Enable UserPromptSubmit for routing */
+ userPromptSubmit: boolean;
+ /** Enable SessionStart hooks */
+ sessionStart: boolean;
+ /** Enable Stop hooks */
+ stop: boolean;
+ /** Enable Notification hooks */
+ notification: boolean;
+ /** Enable PermissionRequest auto-allow for claude-flow */
+ permissionRequest: boolean;
+ /** Hook timeout in milliseconds */
+ timeout: number;
+ /** Continue on hook error */
+ continueOnError: boolean;
+}
+
+/**
+ * Skills configuration
+ */
+export interface SkillsConfig {
+ /** Include core skills (swarm, memory, sparc) */
+ core: boolean;
+ /** Include AgentDB skills */
+ agentdb: boolean;
+ /** Include GitHub integration skills */
+ github: boolean;
+ /** Include Flow Nexus skills */
+ flowNexus: boolean;
+ /** Include V3 implementation skills */
+ v3: boolean;
+ /** Include all available skills */
+ all: boolean;
+}
+
+/**
+ * Commands configuration
+ */
+export interface CommandsConfig {
+ /** Include core commands */
+ core: boolean;
+ /** Include analysis commands */
+ analysis: boolean;
+ /** Include automation commands */
+ automation: boolean;
+ /** Include github commands */
+ github: boolean;
+ /** Include hooks commands */
+ hooks: boolean;
+ /** Include monitoring commands */
+ monitoring: boolean;
+ /** Include optimization commands */
+ optimization: boolean;
+ /** Include SPARC commands */
+ sparc: boolean;
+ /** Include all commands */
+ all: boolean;
+}
+
+/**
+ * Agents configuration
+ */
+export interface AgentsConfig {
+ /** Include core agents (coder, tester, reviewer) */
+ core: boolean;
+ /** Include consensus agents */
+ consensus: boolean;
+ /** Include GitHub agents */
+ github: boolean;
+ /** Include hive-mind agents */
+ hiveMind: boolean;
+ /** Include SPARC agents */
+ sparc: boolean;
+ /** Include swarm coordinators */
+ swarm: boolean;
+ /** Include all agents */
+ all: boolean;
+}
+
+/**
+ * Statusline configuration
+ */
+export interface StatuslineConfig {
+ /** Enable statusline */
+ enabled: boolean;
+ /** Show V3 progress */
+ showProgress: boolean;
+ /** Show security status */
+ showSecurity: boolean;
+ /** Show swarm activity */
+ showSwarm: boolean;
+ /** Show hooks metrics */
+ showHooks: boolean;
+ /** Show performance targets */
+ showPerformance: boolean;
+ /** Refresh interval in milliseconds */
+ refreshInterval: number;
+}
+
+/**
+ * MCP configuration
+ */
+export interface MCPConfig {
+ /** Include claude-flow MCP server */
+ claudeFlow: boolean;
+ /** Include ruv-swarm MCP server */
+ ruvSwarm: boolean;
+ /** Include flow-nexus MCP server */
+ flowNexus: boolean;
+ /** Auto-start MCP server */
+ autoStart: boolean;
+ /** Server port */
+ port: number;
+}
+
+/**
+ * Runtime configuration (.claude-flow/)
+ */
+export interface RuntimeConfig {
+ /** Swarm topology */
+ topology: 'mesh' | 'hierarchical' | 'hierarchical-mesh' | 'adaptive';
+ /** Maximum agents */
+ maxAgents: number;
+ /** Memory backend */
+ memoryBackend: 'memory' | 'sqlite' | 'agentdb' | 'hybrid';
+ /** Enable HNSW indexing */
+ enableHNSW: boolean;
+ /** Enable neural learning */
+ enableNeural: boolean;
+}
+
+/**
+ * Complete init options
+ */
+export interface InitOptions {
+ /** Target directory */
+ targetDir: string;
+ /** Force overwrite existing files */
+ force: boolean;
+ /** Run in interactive mode */
+ interactive: boolean;
+ /** Components to initialize */
+ components: InitComponents;
+ /** Hooks configuration */
+ hooks: HooksConfig;
+ /** Skills configuration */
+ skills: SkillsConfig;
+ /** Commands configuration */
+ commands: CommandsConfig;
+ /** Agents configuration */
+ agents: AgentsConfig;
+ /** Statusline configuration */
+ statusline: StatuslineConfig;
+ /** MCP configuration */
+ mcp: MCPConfig;
+ /** Runtime configuration */
+ runtime: RuntimeConfig;
+}
+
+/**
+ * Default init options - full V3 setup
+ */
+export const DEFAULT_INIT_OPTIONS: InitOptions = {
+ targetDir: process.cwd(),
+ force: false,
+ interactive: true,
+ components: {
+ settings: true,
+ skills: true,
+ commands: true,
+ agents: true,
+ helpers: true,
+ statusline: true,
+ mcp: true,
+ runtime: true,
+ },
+ hooks: {
+ preToolUse: true,
+ postToolUse: true,
+ userPromptSubmit: true,
+ sessionStart: true,
+ stop: true,
+ notification: true,
+ permissionRequest: true,
+ timeout: 5000,
+ continueOnError: true,
+ },
+ skills: {
+ core: true,
+ agentdb: true,
+ github: true,
+ flowNexus: false,
+ v3: true,
+ all: false,
+ },
+ commands: {
+ core: true,
+ analysis: true,
+ automation: true,
+ github: true,
+ hooks: true,
+ monitoring: true,
+ optimization: true,
+ sparc: true,
+ all: false,
+ },
+ agents: {
+ core: true,
+ consensus: false,
+ github: true,
+ hiveMind: true,
+ sparc: true,
+ swarm: true,
+ all: false,
+ },
+ statusline: {
+ enabled: true,
+ showProgress: true,
+ showSecurity: true,
+ showSwarm: true,
+ showHooks: true,
+ showPerformance: true,
+ refreshInterval: 5000,
+ },
+ mcp: {
+ claudeFlow: true,
+ ruvSwarm: false,
+ flowNexus: false,
+ autoStart: false,
+ port: 3000,
+ },
+ runtime: {
+ topology: 'hierarchical-mesh',
+ maxAgents: 15,
+ memoryBackend: 'hybrid',
+ enableHNSW: true,
+ enableNeural: true,
+ },
+};
+
+/**
+ * Minimal init options
+ */
+export const MINIMAL_INIT_OPTIONS: InitOptions = {
+ ...DEFAULT_INIT_OPTIONS,
+ components: {
+ settings: true,
+ skills: true,
+ commands: false,
+ agents: false,
+ helpers: false,
+ statusline: false,
+ mcp: true,
+ runtime: true,
+ },
+ hooks: {
+ ...DEFAULT_INIT_OPTIONS.hooks,
+ userPromptSubmit: false,
+ stop: false,
+ notification: false,
+ },
+ skills: {
+ core: true,
+ agentdb: false,
+ github: false,
+ flowNexus: false,
+ v3: false,
+ all: false,
+ },
+ agents: {
+ core: true,
+ consensus: false,
+ github: false,
+ hiveMind: false,
+ sparc: false,
+ swarm: false,
+ all: false,
+ },
+ runtime: {
+ topology: 'mesh',
+ maxAgents: 5,
+ memoryBackend: 'memory',
+ enableHNSW: false,
+ enableNeural: false,
+ },
+};
+
+/**
+ * Full init options (everything enabled)
+ */
+export const FULL_INIT_OPTIONS: InitOptions = {
+ ...DEFAULT_INIT_OPTIONS,
+ components: {
+ settings: true,
+ skills: true,
+ commands: true,
+ agents: true,
+ helpers: true,
+ statusline: true,
+ mcp: true,
+ runtime: true,
+ },
+ skills: {
+ core: true,
+ agentdb: true,
+ github: true,
+ flowNexus: true,
+ v3: true,
+ all: true,
+ },
+ commands: {
+ ...DEFAULT_INIT_OPTIONS.commands,
+ all: true,
+ },
+ agents: {
+ ...DEFAULT_INIT_OPTIONS.agents,
+ all: true,
+ },
+ mcp: {
+ claudeFlow: true,
+ ruvSwarm: true,
+ flowNexus: true,
+ autoStart: false,
+ port: 3000,
+ },
+};
+
+/**
+ * Init result
+ */
+export interface InitResult {
+ success: boolean;
+ created: {
+ directories: string[];
+ files: string[];
+ };
+ skipped: string[];
+ errors: string[];
+ summary: {
+ skillsCount: number;
+ commandsCount: number;
+ agentsCount: number;
+ hooksEnabled: number;
+ };
+}
diff --git a/v3/@claude-flow/hooks/src/bridge/official-hooks-bridge.ts b/v3/@claude-flow/hooks/src/bridge/official-hooks-bridge.ts
new file mode 100644
index 0000000000..70e4670344
--- /dev/null
+++ b/v3/@claude-flow/hooks/src/bridge/official-hooks-bridge.ts
@@ -0,0 +1,378 @@
+/**
+ * Official Claude Code Hooks Bridge
+ *
+ * Maps V3 internal hook events to official Claude Code hook events.
+ * This bridge enables seamless integration between claude-flow's
+ * internal hook system and the official Claude Code plugin API.
+ *
+ * @module v3/hooks/bridge/official-hooks-bridge
+ */
+
+import { HookEvent, HookPriority, type HookHandler, type HookContext, type HookResult } from '../types.js';
+
+/**
+ * Official Claude Code hook event types
+ * Based on https://code.claude.com/docs/en/hooks
+ */
+export type OfficialHookEvent =
+ | 'PreToolUse'
+ | 'PostToolUse'
+ | 'UserPromptSubmit'
+ | 'PermissionRequest'
+ | 'Notification'
+ | 'Stop'
+ | 'SubagentStop'
+ | 'PreCompact'
+ | 'SessionStart';
+
+/**
+ * Official hook input structure (received via stdin)
+ */
+export interface OfficialHookInput {
+ session_id: string;
+ transcript_path: string;
+ cwd: string;
+ permission_mode: string;
+ hook_event_name: OfficialHookEvent;
+
+ // Tool-specific fields
+ tool_name?: string;
+ tool_input?: Record<string, unknown>;
+ tool_output?: unknown;
+ tool_success?: boolean;
+ tool_exit_code?: number;
+
+ // Prompt-specific fields
+ prompt?: string;
+
+ // Notification-specific fields
+ notification_message?: string;
+ notification_level?: 'info' | 'warning' | 'error';
+}
+
+/**
+ * Official hook output structure (returned via stdout)
+ */
+export interface OfficialHookOutput {
+ /** Decision for permission/flow control */
+ decision?: 'allow' | 'deny' | 'block' | 'ask' | 'approve' | 'stop' | 'continue';
+
+ /** Reason for the decision */
+ reason?: string;
+
+ /** Whether to continue processing (false stops Claude) */
+ continue?: boolean;
+
+ /** Modified tool input (for PreToolUse) */
+ updatedInput?: Record<string, unknown>;
+
+ /** Suppress the tool call result display */
+ suppressOutput?: boolean;
+}
+
+/**
+ * Mapping from V3 HookEvent to Official hook events
+ */
+export const V3_TO_OFFICIAL_HOOK_MAP: Record<HookEvent, OfficialHookEvent | null> = {
+ // Direct mappings
+ [HookEvent.PreToolUse]: 'PreToolUse',
+ [HookEvent.PostToolUse]: 'PostToolUse',
+ [HookEvent.SessionStart]: 'SessionStart',
+
+ // File operations map to tool hooks with matchers
+ [HookEvent.PreEdit]: 'PreToolUse', // matcher: Edit|Write|MultiEdit
+ [HookEvent.PostEdit]: 'PostToolUse', // matcher: Edit|Write|MultiEdit
+ [HookEvent.PreRead]: 'PreToolUse', // matcher: Read
+ [HookEvent.PostRead]: 'PostToolUse', // matcher: Read
+
+ // Command operations map to tool hooks
+ [HookEvent.PreCommand]: 'PreToolUse', // matcher: Bash
+ [HookEvent.PostCommand]: 'PostToolUse', // matcher: Bash
+
+ // Task operations
+ [HookEvent.PreTask]: 'UserPromptSubmit',
+ [HookEvent.PostTask]: 'PostToolUse', // matcher: Task
+ [HookEvent.TaskProgress]: null, // Internal only
+
+ // Session operations
+ [HookEvent.SessionEnd]: 'Stop',
+ [HookEvent.SessionRestore]: 'SessionStart',
+
+ // Agent operations
+ [HookEvent.AgentSpawn]: 'PostToolUse', // matcher: Task
+ [HookEvent.AgentTerminate]: 'SubagentStop',
+
+ // Routing (internal)
+ [HookEvent.PreRoute]: 'UserPromptSubmit',
+ [HookEvent.PostRoute]: null, // Internal only
+
+ // Learning (internal)
+ [HookEvent.PatternLearned]: null, // Internal only
+ [HookEvent.PatternConsolidated]: null, // Internal only
+};
+
+/**
+ * Tool matchers for V3 events that map to PreToolUse/PostToolUse
+ */
+export const V3_TOOL_MATCHERS: Partial<Record<HookEvent, string>> = {
+ [HookEvent.PreEdit]: '^(Write|Edit|MultiEdit)$',
+ [HookEvent.PostEdit]: '^(Write|Edit|MultiEdit)$',
+ [HookEvent.PreRead]: '^Read$',
+ [HookEvent.PostRead]: '^Read$',
+ [HookEvent.PreCommand]: '^Bash$',
+ [HookEvent.PostCommand]: '^Bash$',
+ [HookEvent.PreTask]: '^Task$',
+ [HookEvent.PostTask]: '^Task$',
+ [HookEvent.AgentSpawn]: '^Task$',
+};
+
+/**
+ * Bridge class for converting between V3 and official hooks
+ */
+export class OfficialHooksBridge {
+ /**
+ * Convert official hook input to V3 HookContext
+ */
+ static toV3Context(input: OfficialHookInput): HookContext {
+ const event = this.officialToV3Event(input.hook_event_name, input.tool_name);
+
+ const context: HookContext = {
+ event,
+ timestamp: new Date(),
+ metadata: {
+ session_id: input.session_id,
+ transcript_path: input.transcript_path,
+ cwd: input.cwd,
+ permission_mode: input.permission_mode,
+ },
+ };
+
+ // Add tool information
+ if (input.tool_name) {
+ context.tool = {
+ name: input.tool_name,
+ parameters: input.tool_input ?? {},
+ };
+ }
+
+ // Add file information for file operations
+ if (input.tool_name && ['Write', 'Edit', 'MultiEdit', 'Read'].includes(input.tool_name)) {
+ context.file = {
+ path: (input.tool_input?.file_path as string) ?? '',
+ operation: input.tool_name === 'Read' ? 'read' : 'modify',
+ };
+ }
+
+ // Add command information for Bash
+ if (input.tool_name === 'Bash') {
+ context.command = {
+ raw: (input.tool_input?.command as string) ?? '',
+ workingDirectory: input.cwd,
+ exitCode: input.tool_exit_code,
+ output: typeof input.tool_output === 'string' ? input.tool_output : undefined,
+ };
+ }
+
+ // Add task information for Task tool
+ if (input.tool_name === 'Task') {
+ context.task = {
+ id: `task-${Date.now()}`,
+ description: (input.tool_input?.prompt as string) ?? '',
+ agent: input.tool_input?.subagent_type as string,
+ };
+ }
+
+ // Add session information
+ context.session = {
+ id: input.session_id,
+ startedAt: new Date(),
+ };
+
+ // Add prompt for UserPromptSubmit
+ if (input.prompt) {
+ context.routing = {
+ task: input.prompt,
+ };
+ }
+
+ return context;
+ }
+
+ /**
+ * Convert V3 HookResult to official hook output
+ */
+ static toOfficialOutput(result: HookResult, event: OfficialHookEvent): OfficialHookOutput {
+ const output: OfficialHookOutput = {};
+
+ // Map abort to decision
+ if (result.abort) {
+ output.decision = event === 'PermissionRequest' ? 'deny' : 'block';
+ output.continue = false;
+ } else if (result.success) {
+ output.decision = event === 'PermissionRequest' ? 'allow' : 'continue';
+ output.continue = true;
+ }
+
+ // Add reason
+ if (result.error) {
+ output.reason = result.error;
+ } else if (result.message) {
+ output.reason = result.message;
+ }
+
+ // Pass through updated input if present
+ if (result.data?.updatedInput) {
+ output.updatedInput = result.data.updatedInput as Record<string, unknown>;
+ }
+
+ return output;
+ }
+
+ /**
+ * Convert official hook event to V3 HookEvent
+ */
+ static officialToV3Event(officialEvent: OfficialHookEvent, toolName?: string): HookEvent {
+ // Handle tool-specific mappings
+ if (officialEvent === 'PreToolUse' && toolName) {
+ if (['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
+ return HookEvent.PreEdit;
+ }
+ if (toolName === 'Read') {
+ return HookEvent.PreRead;
+ }
+ if (toolName === 'Bash') {
+ return HookEvent.PreCommand;
+ }
+ if (toolName === 'Task') {
+ return HookEvent.PreTask;
+ }
+ return HookEvent.PreToolUse;
+ }
+
+ if (officialEvent === 'PostToolUse' && toolName) {
+ if (['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
+ return HookEvent.PostEdit;
+ }
+ if (toolName === 'Read') {
+ return HookEvent.PostRead;
+ }
+ if (toolName === 'Bash') {
+ return HookEvent.PostCommand;
+ }
+ if (toolName === 'Task') {
+ return HookEvent.PostTask;
+ }
+ return HookEvent.PostToolUse;
+ }
+
+ // Direct mappings
+ const mapping: Record<OfficialHookEvent, HookEvent> = {
+ PreToolUse: HookEvent.PreToolUse,
+ PostToolUse: HookEvent.PostToolUse,
+ UserPromptSubmit: HookEvent.PreTask,
+ PermissionRequest: HookEvent.PreToolUse,
+ Notification: HookEvent.PostTask, // Closest match
+ Stop: HookEvent.SessionEnd,
+ SubagentStop: HookEvent.AgentTerminate,
+ PreCompact: HookEvent.SessionEnd, // Closest match
+ SessionStart: HookEvent.SessionStart,
+ };
+
+ return mapping[officialEvent] ?? HookEvent.PreToolUse;
+ }
+
+ /**
+ * Get tool matcher for a V3 event
+ */
+ static getToolMatcher(event: HookEvent): string | null {
+ return V3_TOOL_MATCHERS[event] ?? null;
+ }
+
+ /**
+ * Check if V3 event maps to an official hook
+ */
+ static hasOfficialMapping(event: HookEvent): boolean {
+ return V3_TO_OFFICIAL_HOOK_MAP[event] !== null;
+ }
+
+ /**
+ * Create a CLI command for a V3 hook handler
+ */
+ static createCLICommand(event: HookEvent, handler: string): string {
+ const baseCommand = 'npx claude-flow@alpha hooks';
+
+ switch (event) {
+ case HookEvent.PreEdit:
+ return `${baseCommand} pre-edit --file "$TOOL_INPUT_file_path"`;
+ case HookEvent.PostEdit:
+ return `${baseCommand} post-edit --file "$TOOL_INPUT_file_path" --success "$TOOL_SUCCESS" --train-patterns`;
+ case HookEvent.PreCommand:
+ return `${baseCommand} pre-command --command "$TOOL_INPUT_command"`;
+ case HookEvent.PostCommand:
+ return `${baseCommand} post-command --command "$TOOL_INPUT_command" --success "$TOOL_SUCCESS"`;
+ case HookEvent.PreTask:
+ return `${baseCommand} pre-task --description "$PROMPT"`;
+ case HookEvent.PostTask:
+ return `${baseCommand} post-task --task-id "$TOOL_RESULT_agent_id" --analyze-performance`;
+ case HookEvent.SessionStart:
+ return `${baseCommand} session-start --session-id "$SESSION_ID" --load-context`;
+ case HookEvent.SessionEnd:
+ return `${baseCommand} session-end --session-id "$SESSION_ID" --export-metrics`;
+ default:
+ return `${baseCommand} ${handler}`;
+ }
+ }
+}
+
+/**
+ * Process stdin from official Claude Code hook system
+ */
+export async function processOfficialHookInput(): Promise<OfficialHookInput | null> {
+ return new Promise((resolve) => {
+ let data = '';
+
+ process.stdin.setEncoding('utf8');
+ process.stdin.on('readable', () => {
+ let chunk;
+ while ((chunk = process.stdin.read()) !== null) {
+ data += chunk;
+ }
+ });
+
+ process.stdin.on('end', () => {
+ try {
+ resolve(JSON.parse(data));
+ } catch {
+ resolve(null);
+ }
+ });
+
+ // Handle case where no stdin (testing)
+ setTimeout(() => {
+ if (!data) {
+ resolve(null);
+ }
+ }, 100);
+ });
+}
+
+/**
+ * Output result to official Claude Code hook system
+ */
+export function outputOfficialHookResult(output: OfficialHookOutput): void {
+ console.log(JSON.stringify(output));
+}
+
+/**
+ * Execute a V3 handler and bridge to official output
+ */
+export async function executeWithBridge(
+ input: OfficialHookInput,
+ handler: HookHandler
+): Promise<OfficialHookOutput> {
+ const context = OfficialHooksBridge.toV3Context(input);
+ const result = await handler(context);
+ return OfficialHooksBridge.toOfficialOutput(result, input.hook_event_name);
+}
+
+export default OfficialHooksBridge;
diff --git a/v3/@claude-flow/hooks/src/index.ts b/v3/@claude-flow/hooks/src/index.ts
index af6cf0a867..ca8d9085d0 100644
--- a/v3/@claude-flow/hooks/src/index.ts
+++ b/v3/@claude-flow/hooks/src/index.ts
@@ -63,6 +63,19 @@ export {
type MCPTool,
} from './mcp/index.js';
+// Official Claude Code Hooks Bridge
+export {
+ OfficialHooksBridge,
+ V3_TO_OFFICIAL_HOOK_MAP,
+ V3_TOOL_MATCHERS,
+ processOfficialHookInput,
+ outputOfficialHookResult,
+ executeWithBridge,
+ type OfficialHookEvent,
+ type OfficialHookInput,
+ type OfficialHookOutput,
+} from './bridge/official-hooks-bridge.js';
+
// Version
export const VERSION = '3.0.0-alpha.1';
diff --git a/v3/implementation/PLUGIN_INTEGRATION.md b/v3/implementation/PLUGIN_INTEGRATION.md
new file mode 100644
index 0000000000..9082f41cc3
--- /dev/null
+++ b/v3/implementation/PLUGIN_INTEGRATION.md
@@ -0,0 +1,240 @@
+# Claude Flow Plugin Integration
+
+## Overview
+
+This document describes how claude-flow integrates with the official Claude Code plugin system.
+
+## Plugin Structure
+
+```
+plugin/
+β”œβ”€β”€ .claude-plugin/
+β”‚ └── plugin.json # Official plugin manifest
+β”œβ”€β”€ .mcp.json # MCP server bundle
+β”œβ”€β”€ hooks/
+β”‚ └── hooks.json # Hook configurations
+β”œβ”€β”€ skills -> ../.claude/skills # 60+ skills
+β”œβ”€β”€ commands -> ../.claude/commands # 100+ commands
+└── agents -> ../v2/.claude/agents # 80+ agents
+```
+
+## Official Claude Code Integration Points
+
+### 1. Plugin Manifest (`plugin.json`)
+
+```json
+{
+ "name": "claude-flow",
+ "version": "3.0.0",
+ "capabilities": {
+ "skills": true,
+ "commands": true,
+ "agents": true,
+ "hooks": true,
+ "mcpServers": true
+ }
+}
+```
+
+### 2. Hook Event Mapping
+
+| V3 Internal Event | Official Claude Code Event | Tool Matcher |
+|-------------------|---------------------------|--------------|
+| `PreEdit` | `PreToolUse` | `^(Write\|Edit\|MultiEdit)$` |
+| `PostEdit` | `PostToolUse` | `^(Write\|Edit\|MultiEdit)$` |
+| `PreCommand` | `PreToolUse` | `^Bash$` |
+| `PostCommand` | `PostToolUse` | `^Bash$` |
+| `PreTask` | `UserPromptSubmit` | - |
+| `PostTask` | `PostToolUse` | `^Task$` |
+| `SessionStart` | `SessionStart` | - |
+| `SessionEnd` | `Stop` | - |
+| `AgentSpawn` | `PostToolUse` | `^Task$` |
+| `AgentTerminate` | `SubagentStop` | - |
+| `PreRoute` | `UserPromptSubmit` | - |
+
+### 3. MCP Server Bundle
+
+The plugin bundles three MCP servers:
+
+1. **claude-flow** (required): Core swarm coordination
+2. **ruv-swarm** (optional): Enhanced topology patterns
+3. **flow-nexus** (optional): Cloud orchestration
+
+### 4. Skills Integration
+
+Skills follow the official SKILL.md format:
+
+```yaml
+---
+name: skill-name
+description: What this skill does
+allowed-tools: Read, Write, Bash
+---
+
+# Skill Name
+
+[Instructions for Claude]
+```
+
+## V3 Hooks Bridge
+
+The `@claude-flow/hooks` package includes an official hooks bridge:
+
+```typescript
+import {
+ OfficialHooksBridge,
+ processOfficialHookInput,
+ outputOfficialHookResult,
+ executeWithBridge,
+} from '@claude-flow/hooks';
+
+// Process input from Claude Code
+const input = await processOfficialHookInput();
+
+// Convert to V3 context
+const context = OfficialHooksBridge.toV3Context(input);
+
+// Execute V3 handler
+const result = await handler(context);
+
+// Convert back to official output
+const output = OfficialHooksBridge.toOfficialOutput(result, input.hook_event_name);
+outputOfficialHookResult(output);
+```
+
+## Installation
+
+### Via Plugin Command (Recommended)
+
+```bash
+# Add plugin marketplace
+/plugin marketplace add claude-flow https://github.com/ruvnet/claude-flow
+
+# Install plugin
+/plugin install claude-flow
+```
+
+### Manual Installation
+
+```bash
+# Clone and link
+git clone https://github.com/ruvnet/claude-flow
+claude --plugin-dir ./claude-flow/plugin
+```
+
+### Via npx Init
+
+```bash
+npx claude-flow@alpha init --hooks
+```
+
+## Configuration
+
+### Enable All Hooks
+
+Add to `.claude/settings.json`:
+
+```json
+{
+ "hooks": {
+ "PreToolUse": [...],
+ "PostToolUse": [...],
+ "UserPromptSubmit": [...],
+ "SessionStart": [...],
+ "Stop": [...]
+ }
+}
+```
+
+### Selective Hooks
+
+Enable only specific hooks by choosing matchers:
+
+```json
+{
+ "hooks": {
+ "PreToolUse": [
+ {
+ "matcher": "^(Write|Edit)$",
+ "hooks": [{ "type": "command", "command": "npx claude-flow@alpha hooks pre-edit" }]
+ }
+ ]
+ }
+}
+```
+
+## MCP Tool Access
+
+After installation, MCP tools are available:
+
+- `mcp__claude-flow__swarm_init`
+- `mcp__claude-flow__agent_spawn`
+- `mcp__claude-flow__task_orchestrate`
+- `mcp__claude-flow__memory_usage`
+- `mcp__claude-flow__hooks_route`
+- `mcp__claude-flow__hooks_metrics`
+
+## Marketplace Publishing
+
+### Create Marketplace Entry
+
+```json
+{
+ "name": "claude-flow-marketplace",
+ "plugins": [
+ {
+ "name": "claude-flow",
+ "description": "Multi-agent swarm coordination",
+ "version": "3.0.0",
+ "path": "plugin"
+ }
+ ]
+}
+```
+
+### Host on GitHub
+
+1. Push to repository
+2. Add marketplace: `/plugin marketplace add name https://github.com/user/repo`
+3. Users install: `/plugin install claude-flow@name`
+
+## Architecture
+
+```
+β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
+β”‚ Claude Code β”‚
+β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
+β”‚ Official Hooks API β”‚
+β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
+β”‚ β”‚ PreToolUse β”‚ PostToolUse β”‚ SessionStartβ”‚ UserPrompt β”‚ β”‚
+β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
+β”‚ β”‚ β”‚ β”‚ β”‚ β”‚
+β”‚ β–Ό β–Ό β–Ό β–Ό β”‚
+β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”β”‚
+β”‚ β”‚ Official Hooks Bridge β”‚β”‚
+β”‚ β”‚ (v3/@claude-flow/hooks/src/bridge/official-hooks-bridge)β”‚β”‚
+β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜β”‚
+β”‚ β”‚ β”‚ β”‚ β”‚ β”‚
+β”‚ β–Ό β–Ό β–Ό β–Ό β”‚
+β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
+β”‚ β”‚ PreEdit β”‚ PostEdit β”‚ SessionStartβ”‚ PreTask β”‚ β”‚
+β”‚ β”‚ PreCommand β”‚ PostCommand β”‚ SessionEnd β”‚ PostTask β”‚ β”‚
+β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
+β”‚ V3 Hooks System β”‚
+β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
+β”‚ @claude-flow/hooks β”‚
+β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
+β”‚ β”‚ Registry β”‚ Executor β”‚ Daemons β”‚ MCP Tools β”‚ β”‚
+β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
+β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
+β”‚ Skills β”‚ Commands β”‚ Agents β”‚ MCP Servers β”‚
+β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
+```
+
+## Benefits
+
+1. **Seamless Integration**: V3 hooks map directly to official events
+2. **Full Feature Access**: 60+ skills, 100+ commands, 80+ agents
+3. **MCP Bundling**: All servers configured in one file
+4. **Marketplace Ready**: Standard plugin format for distribution
+5. **Backward Compatible**: Works with existing `.claude/` configurations