Plugin Sdk

Plugin SDK — Unified Plugin Development Framework

Purpose

The @claude-flow/plugins module provides the unified Plugin SDK for Claude Flow v3, covering the full plugin development lifecycle including plugin registration, lifecycle management, Worker capabilities, Hook system, LLM provider integration, MCP tool development, security utilities, and RuVector integration for vector search and graph neural networks.

Core Components

Plugin Interface

Every plugin implements the IPlugin interface:

interface IPlugin extends EventEmitter {
  readonly metadata: PluginMetadata;
  state: PluginLifecycleState;
  initialize(context: PluginContext): Promise<void>;
  shutdown(): Promise<void>;
  healthCheck(): Promise<HealthCheckResult>;

  // Optional extension points
  registerAgentTypes?(): AgentTypeDefinition[];
  registerTaskTypes?(): TaskTypeDefinition[];
  registerMCPTools?(): MCPToolDefinition[];
  registerCLICommands?(): CLICommandDefinition[];
  registerMemoryBackends?(): MemoryBackendFactory[];
  registerHooks?(): HookDefinition[];
  registerWorkers?(): WorkerDefinition[];
  registerProviders?(): LLMProviderDefinition[];
}

Plugin Lifecycle States

uninitialized -> initializing -> initialized -> shutting-down -> shutdown

Error state: error (can occur from initializing or initialized)

BasePlugin (Abstract Base Class)

import { BasePlugin } from '@claude-flow/plugins';

class MyPlugin extends BasePlugin {
  constructor() {
    super({
      name: 'my-plugin',
      version: '1.0.0',
      description: 'My custom plugin',
      dependencies: ['other-plugin'],
    });
  }

  protected async onInitialize(): Promise<void> {
    this.logger.info('Plugin initialized');
  }

  protected async onShutdown(): Promise<void> {
    this.logger.info('Plugin shutting down');
  }

  protected async onHealthCheck(): Promise<Record<string, { healthy: boolean }>> {
    return { database: { healthy: true } };
  }

  registerMCPTools(): MCPToolDefinition[] {
    return [{
      name: 'my-tool',
      description: 'My custom tool',
      inputSchema: { type: 'object', properties: {} },
      handler: async (input) => ({
        content: [{ type: 'text', text: 'Hello!' }]
      })
    }];
  }
}

Simple Plugin (Functional API)

import { createSimplePlugin } from '@claude-flow/plugins';

const plugin = createSimplePlugin({
  name: 'simple-plugin',
  version: '1.0.0',
  onInit: async (ctx) => { /* ... */ },
  onShutdown: async () => { /* ... */ },
  mcpTools: [/* ... */],
  hooks: [/* ... */],
});

Plugin Registry

import { getDefaultRegistry, PluginRegistry } from '@claude-flow/plugins';

const registry = getDefaultRegistry();

// Register a plugin
await registry.register(myPlugin);

// Get registry stats
const stats = registry.getStats();
// { totalPlugins, initialized, errored, ... }

PluginBuilder (Fluent API)

import { PluginBuilder } from '@claude-flow/plugins';

const myPlugin = new PluginBuilder('my-plugin', '1.0.0')
  .withDescription('My awesome plugin')
  .withMCPTools([/* tool definitions */])
  .withHooks([/* hook definitions */])
  .withWorkers([/* worker definitions */])
  .build();

Extension Points

MCP Tools

interface MCPToolDefinition {
  name: string;
  description: string;
  inputSchema: object;
  handler: (input: unknown) => Promise<{ content: ContentBlock[] }>;
}

Hooks

interface HookDefinition {
  event: string;           // e.g., 'pre-command', 'post-edit'
  priority: number;        // Execution order (lower = earlier)
  handler: (context: HookContext) => Promise<HookResult>;
}

Workers

interface WorkerDefinition {
  name: string;
  capabilities: string[];
  handler: (task: WorkerTask) => Promise<WorkerResult>;
}

LLM Providers

interface LLMProviderDefinition {
  name: string;
  models: string[];
  factory: (config: ProviderConfig) => ILLMProvider;
}

RuVector Integration

Vector search, graph neural networks, and advanced ML integrations:

Vector Bridge

import { RuVectorBridge } from '@claude-flow/plugins';
// Connects plugins to RuVector for HNSW-indexed vector search

Quantization

import { Quantization } from '@claude-flow/plugins';
// Supports vector quantization for memory-efficient storage

Streaming

import { Streaming } from '@claude-flow/plugins';
// Streaming large data through vector pipelines

Self-Learning

import { SelfLearning } from '@claude-flow/plugins';
// Plugins that learn from usage patterns

Graph Neural Networks

import { GNN } from '@claude-flow/plugins';
// Graph-based reasoning over plugin interactions

Attention Executor

import { AttentionExecutor, AttentionAdvanced } from '@claude-flow/plugins';
// Attention-based execution routing and advanced attention mechanisms

Hyperbolic Embeddings

import { Hyperbolic } from '@claude-flow/plugins';
// Hyperbolic space embeddings for hierarchical data

Security

import { Security } from '@claude-flow/plugins';
// Plugin sandboxing, permission validation, input sanitization

Agentic Flow Integration

import { AgenticFlowIntegration } from '@claude-flow/plugins';
// Connects plugins to the agentic-flow optimization layer

Example: RuVector Plugin Development

// Reasoning Bank plugin
import { ReasoningBankPlugin } from '@claude-flow/plugins/examples/ruvector-plugins';

// SONA Learning plugin
import { SonaLearningPlugin } from '@claude-flow/plugins/examples/ruvector-plugins';

// Semantic Code Search plugin
import { SemanticCodeSearchPlugin } from '@claude-flow/plugins/examples/ruvector-plugins';

// Intent Router plugin
import { IntentRouterPlugin } from '@claude-flow/plugins/examples/ruvector-plugins';

// Hook Pattern Library plugin
import { HookPatternLibraryPlugin } from '@claude-flow/plugins/examples/ruvector-plugins';

// MCP Tool Optimizer plugin
import { MCPToolOptimizerPlugin } from '@claude-flow/plugins/examples/ruvector-plugins';

Plugin Validation

import { validatePlugin, validatePluginMetadata } from '@claude-flow/plugins';

const errors = validatePlugin(myPlugin);
const metadataErrors = validatePluginMetadata(myPlugin.metadata);

Plugin Events

• PLUGIN_EVENTS.INITIALIZED — Plugin successfully initialized
• PLUGIN_EVENTS.SHUTDOWN — Plugin shutdown complete
• PLUGIN_EVENTS.ERROR — Plugin encountered an error
• stateChange — Plugin lifecycle state changed