@claude-flow/pluginsUnified Plugin SDK for Claude Flow V3
A comprehensive plugin development framework providing workers, hooks, providers, and security utilities for building Claude Flow extensions.
Installationnpm install @claude-flow/plugins Quick Start Create a Plugin with the Builderimport { PluginBuilder, HookEvent, HookPriority } from '@claude-flow/plugins' ;
const myPlugin = new PluginBuilder ( 'my-awesome-plugin' , '1.0.0' )
. withDescription ( 'My awesome plugin for Claude Flow' )
. withAuthor ( 'Your Name' )
. withMCPTools ( [
{
name: 'greet' ,
description: 'Greet a user' ,
inputSchema: {
type: 'object' ,
properties: {
name: { type: 'string' , description: 'Name to greet' }
} ,
required: [ 'name' ]
} ,
handler : async ( input) => ( {
content: [ { type: 'text' , text: ` Hello, ${ input. name} ! ` } ]
} )
}
] )
. withHooks ( [
{
event: HookEvent. PostTaskComplete,
priority: HookPriority. Normal,
handler : async ( ctx) => {
console . log ( 'Task completed:' , ctx. data) ;
return { success: true } ;
}
}
] )
. build ( ) ;
import { getDefaultRegistry } from '@claude-flow/plugins' ;
await getDefaultRegistry ( ) . register ( myPlugin) ; Quick Plugin Creatorsimport { createToolPlugin, createHooksPlugin, createWorkerPlugin } from '@claude-flow/plugins' ;
const toolPlugin = createToolPlugin ( 'my-tools' , '1.0.0' , [
{ name: 'tool1' , description: '...' , inputSchema: { ... } , handler : async ( ) => { ... } }
] ) ;
const hooksPlugin = createHooksPlugin ( 'my-hooks' , '1.0.0' , [
{ event: HookEvent. PreTaskExecute, handler : async ( ctx) => ( { success: true } ) }
] ) ;
const workerPlugin = createWorkerPlugin ( 'my-workers' , '1.0.0' , [
{ type: 'coder' , name: 'main-coder' , capabilities: [ 'code-generation' ] }
] ) ; Featuresimport { MCPToolBuilder } from '@claude-flow/plugins' ;
const tool = new MCPToolBuilder ( 'calculate' )
. withDescription ( 'Perform calculations' )
. addStringParam ( 'expression' , 'Math expression' , { required: true } )
. addBooleanParam ( 'verbose' , 'Show steps' , { default : false } )
. withHandler ( async ( input) => {
const result = eval ( input. expression) ;
return { content: [ { type: 'text' , text: ` Result: ${ result} ` } ] } ;
} )
. build ( ) ; 🎣 Hook Systemimport { HookBuilder, HookFactory, HookRegistry, HookEvent, HookPriority } from '@claude-flow/plugins' ;
const hook = new HookBuilder ( HookEvent. PreAgentSpawn)
. withName ( 'validate-agent' )
. withPriority ( HookPriority. High)
. when ( ( ctx) => ctx. data?. type === 'coder' )
. transform ( ( data) => ( { ... data, validated: true } ) )
. handle ( async ( ctx) => {
return { success: true , data: ctx. data, modified: true } ;
} )
. build ( ) ;
const logger = HookFactory. createLogger ( HookEvent. PostTaskComplete, console ) ;
const rateLimiter = HookFactory. createRateLimiter ( HookEvent. PreToolCall, { maxPerMinute: 100 } ) ;
const validator = HookFactory. createValidator ( HookEvent. PreAgentSpawn, ( data) => data. type !== undefined ) ; 👷 Worker Poolimport { WorkerPool, WorkerFactory } from '@claude-flow/plugins' ;
const pool = new WorkerPool ( {
minWorkers: 2 ,
maxWorkers: 10 ,
taskQueueSize: 100
} ) ;
const coder = await pool. spawn ( WorkerFactory. createCoder ( 'main-coder' ) ) ;
const reviewer = await pool. spawn ( WorkerFactory. createReviewer ( 'code-reviewer' ) ) ;
const tester = await pool. spawn ( WorkerFactory. createTester ( 'test-runner' ) ) ;
const result = await pool. submit ( {
id: 'task-1' ,
type: 'code-generation' ,
input: { prompt: 'Write a function...' }
} ) ;
await pool. shutdown ( ) ; 🤖 LLM Provider Integrationimport { ProviderRegistry, ProviderFactory, BaseLLMProvider } from '@claude-flow/plugins' ;
const registry = new ProviderRegistry ( {
fallbackChain: [ 'anthropic' , 'openai' ] ,
costOptimization: true
} ) ;
class ClaudeProvider extends BaseLLMProvider {
constructor ( ) {
super ( ProviderFactory. createClaude ( ) ) ;
}
async complete ( request) {
}
}
registry. register ( new ClaudeProvider ( ) ) ;
const response = await registry. execute ( {
model: 'claude-sonnet-4-20250514' ,
messages: [ { role: 'user' , content: 'Hello!' } ]
} ) ; 🔗 Agentic Flow Integrationimport { AgenticFlowBridge, AgentDBBridge } from '@claude-flow/plugins' ;
const agentic = new AgenticFlowBridge ( { maxConcurrentAgents: 15 } ) ;
await agentic. initializeSwarm ( { type: 'hierarchical' , maxAgents: 15 } ) ;
const agent = await agentic. spawnAgent ( {
type: 'coder' ,
capabilities: [ 'typescript' , 'react' ]
} ) ;
const result = await agentic. orchestrateTask ( {
taskType: 'code-generation' ,
input: { prompt: '...' } ,
agentId: agent. id
} ) ;
const agentdb = new AgentDBBridge ( { dimensions: 1536 , indexType: 'hnsw' } ) ;
await agentdb. initialize ( ) ;
await agentdb. store ( 'doc-1' , embeddings, { type: 'document' } ) ;
const similar = await agentdb. search ( queryVector, { limit: 10 } ) ; 🔒 Security Utilitiesimport { Security, createRateLimiter, createResourceLimiter } from '@claude-flow/plugins' ;
const name = Security. validateString ( input, { minLength: 1 , maxLength: 100 } ) ;
const count = Security. validateNumber ( input, { min: 0 , max: 1000 , integer: true } ) ;
const path = Security. validatePath ( input, { allowedExtensions: [ '.ts' , '.js' ] } ) ;
const safePath = Security. safePath ( '/project' , 'src' , userInput) ;
const data = Security. safeJsonParse < Config> ( jsonString) ;
const cmd = Security. validateCommand ( 'npm install' , { allowedCommands: new Set ( [ 'npm' , 'npx' ] ) } ) ;
const limiter = createRateLimiter ( { maxTokens: 100 , refillRate: 10 , refillInterval: 1000 } ) ;
if ( limiter. tryAcquire ( ) ) {
}
const resourceLimiter = createResourceLimiter ( { maxMemoryMB: 512 , maxExecutionTime: 30000 } ) ;
const result = await resourceLimiter. enforce ( async ( ) => {
} ) ; API Reference Core Exports
Export
Description
PluginBuilder
Fluent builder for creating plugins
BasePlugin
Abstract base class for plugins
PluginRegistry
Plugin lifecycle management
getDefaultRegistry()
Get the default plugin registry
SDK Builders
Export
Description
MCPToolBuilder
Build MCP tools with parameters
HookBuilder
Build hooks with conditions and transformers
WorkerBuilder
Build worker definitions
Quick Creators
Export
Description
createToolPlugin()
Create a tool-only plugin
createHooksPlugin()
Create a hooks-only plugin
createWorkerPlugin()
Create a worker plugin
createProviderPlugin()
Create a provider plugin
Hook System
Export
Description
HookRegistry
Central hook management
HookExecutor
Execute hooks with patterns
HookFactory
Pre-built hook creators
HookEvent
All hook event types
HookPriority
Hook priority levels
Workers
Export
Description
WorkerPool
Managed worker pool
WorkerInstance
Individual worker
WorkerFactory
Worker definition factory
Providers
Export
Description
ProviderRegistry
LLM provider management
BaseLLMProvider
Base provider implementation
ProviderFactory
Provider definition factory
Integrations
Export
Description
AgenticFlowBridge
agentic-flow@alpha integration
AgentDBBridge
AgentDB vector storage
Security
Export
Description
Security
All security utilities
validateString/Number/Boolean/Array/Enum
Input validators
safePath/safePathAsync
Path security
safeJsonParse/safeJsonStringify
JSON security
createRateLimiter
Rate limiting
createResourceLimiter
Resource limiting
Hook Eventsenum HookEvent {
SessionStart = 'session:start' ,
SessionEnd = 'session:end' ,
PreAgentSpawn = 'agent:pre-spawn' ,
PostAgentSpawn = 'agent:post-spawn' ,
PreAgentTerminate = 'agent:pre-terminate' ,
PostAgentTerminate = 'agent:post-terminate' ,
PreTaskExecute = 'task:pre-execute' ,
PostTaskComplete = 'task:post-complete' ,
TaskError = 'task:error' ,
PreToolCall = 'tool:pre-call' ,
PostToolCall = 'tool:post-call' ,
PreMemoryStore = 'memory:pre-store' ,
PostMemoryStore = 'memory:post-store' ,
PreMemoryRetrieve = 'memory:pre-retrieve' ,
PostMemoryRetrieve = 'memory:post-retrieve' ,
SwarmInitialized = 'swarm:initialized' ,
SwarmShutdown = 'swarm:shutdown' ,
ConsensusReached = 'swarm:consensus-reached' ,
PreFileRead = 'file:pre-read' ,
PostFileRead = 'file:post-read' ,
PreFileWrite = 'file:pre-write' ,
PostFileWrite = 'file:post-write' ,
PreCommand = 'command:pre-execute' ,
PostCommand = 'command:post-execute' ,
PatternLearned = 'learning:pattern-learned' ,
PatternApplied = 'learning:pattern-applied' ,
} Hook Prioritiesenum HookPriority {
Critical = 1000 ,
High = 750 ,
Normal = 500 ,
Low = 250 ,
Deferred = 0 ,
} Worker Types
coder - Code implementation
reviewer - Code review
tester - Test generation/execution
researcher - Information gathering
planner - Task planning
coordinator - Multi-agent coordination
security - Security analysis
performance - Performance optimization
specialized - Custom capabilities
long-running - Background tasks
Metric
Target
Actual
Plugin load time
< 50ms
~20ms
Hook execution
< 1ms
~0.5ms
Worker spawn
< 100ms
~50ms
Vector search (10K)
< 10ms
~5ms
Testingnpm test
npm run test:watch LicenseMIT