Build Custom Ruflo Plugins with the Plugin Builder API

The plugin system uses a fluent builder API to create MCP tools, lifecycle hooks, background workers, and LLM provider integrations. Plugins integrate into the same coordination ledger, memory system, and hooks pipeline as Ruflo’s built-in capabilities — so custom tools appear natively in Claude Code’s tool palette and custom hooks fire at the same lifecycle events as the core system.

@claude-flow/mcp has zero @claude-flow/* dependencies by design, so plugins stay lightweight even when the full Ruflo CLI is not installed in the target environment. The @claude-flow/plugins builder package imports only what it needs.

Builder Components

Component	Description	Key Features
`PluginBuilder`	Fluent builder for creating plugins	MCP tools, hooks, workers, providers
`MCPToolBuilder`	Build typed MCP tools with validated parameters	String, number, boolean, enum, array, object params
`HookBuilder`	Build hooks with conditions and priorities	Priority ordering, conditional execution
`WorkerPool`	Managed background worker pool	Min/max workers, task queuing, auto-scaling
`ProviderRegistry`	LLM provider management with fallback	Cost optimization, automatic failover

Performance targets: Plugin load < 20ms · Hook execution < 0.5ms · Worker spawn < 50ms

Build Your First Plugin

Scaffold the plugin

The ruflo-plugin-creator scaffold generates a complete project layout with TypeScript configuration, entry points for tools, hooks, and workers, and a test harness.

npx ruflo@latest plugins create --name my-analyzer

This creates the following directory structure:

plugins/my-analyzer/
├── package.json
├── README.md
├── src/
│   ├── index.ts        # Plugin entry point — imports and assembles tools, hooks, workers
│   ├── tools.ts        # MCP tool definitions
│   ├── hooks.ts        # Hook handlers
│   └── workers.ts      # Background workers
└── tests/
    └── index.test.ts

Implement the plugin

Edit src/index.ts to define your plugin’s tools, hooks, and workers using the builder API. The example below creates a code analysis plugin with one MCP tool, a post-task hook that stores results, and a background worker for periodic analysis.

import {
  PluginBuilder,
  MCPToolBuilder,
  HookBuilder,
  WorkerPool,
} from '@claude-flow/plugins';

export const plugin = new PluginBuilder('my-analyzer')
  // ── MCP Tool ──────────────────────────────────────────────────────────
  .addTool(
    new MCPToolBuilder('analyze-code')
      .description('Analyze code quality and suggest improvements')
      .param('code', 'string', 'The source code to analyze', true)
      .param('language', 'string', 'Programming language (default: auto-detect)')
      .param('depth', 'enum', 'Analysis depth', false, ['quick', 'standard', 'deep'])
      .handler(async ({ code, language, depth = 'standard' }) => ({
        issues: [],
        suggestions: [],
        score: 0.95,
        language: language ?? 'typescript',
        depth,
      }))
      .build()
  )

  // ── Post-task Hook ────────────────────────────────────────────────────
  .addHook(
    new HookBuilder('post-task')
      .description('Store code analysis results in memory after task completion')
      .condition(ctx => ctx.taskType === 'code-analysis')
      .priority(10)
      .handler(async (ctx) => {
        await ctx.memory.store({
          key: `analysis-${ctx.taskId}`,
          value: JSON.stringify(ctx.result),
          namespace: 'code-analysis',
        });
      })
      .build()
  )

  // ── Background Worker ─────────────────────────────────────────────────
  .addWorker(
    new WorkerPool('analysis-worker', {
      minWorkers: 1,
      maxWorkers: 4,
      taskTimeout: 30000,
    })
  )

  .build();

Validate

Run the built-in validator to check parameter schemas, hook event names, worker configuration, and package metadata before testing.

npx ruflo@latest plugins validate --name my-analyzer

The validator checks:

All required MCPToolBuilder parameters have correct types
Hook event names are valid (see the full list below)
Worker minWorkers ≤ maxWorkers
package.json has name, version, and main fields

Test

Run the test suite against the scaffolded test harness. Tests spin up an in-process MCP server, fire tool calls, trigger hooks, and assert on outputs without requiring a full Ruflo installation.

npx ruflo@latest plugins test --name my-analyzer

Publish

Publish the plugin to the Ruflo marketplace. The publish step runs validate and test automatically before uploading.

npx ruflo@latest plugins publish --name my-analyzer

After publishing, other users can install your plugin with:

npx ruflo@latest plugins install -n my-analyzer

MCPToolBuilder Parameter Types

Every parameter passed to .param() must have one of the following types. The builder generates a JSON Schema inputSchema from these declarations automatically.

Type	JSON Schema Mapping	Example Use
`string`	`{ "type": "string" }`	File paths, task descriptions, queries
`number`	`{ "type": "number" }`	Thresholds, limits, timeouts
`boolean`	`{ "type": "boolean" }`	Feature flags, `includeTests`
`enum`	`{ "type": "string", "enum": [...] }`	Topology, priority, analysis depth
`array`	`{ "type": "array" }`	Lists of files, agent names
`object`	`{ "type": "object" }`	Structured config blocks

new MCPToolBuilder('my-tool')
  .description('Example with every parameter type')
  .param('name',    'string',  'Display name',         true)
  .param('count',   'number',  'How many items',        false)
  .param('verbose', 'boolean', 'Include debug output',  false)
  .param('mode',    'enum',    'Execution mode',        false, ['fast', 'thorough'])
  .param('files',   'array',   'Paths to process',      false)
  .param('config',  'object',  'Advanced configuration', false)
  .handler(async (input) => { /* ... */ })
  .build()

HookBuilder: All 27 Hook Names

Hook names map to the 27 hooks in Ruflo’s hooks system. Pass any of these as the first argument to new HookBuilder(name).

pre-edit
post-edit
pre-command
post-command
pre-task
post-task

Additionally, plugin hooks may use the object-style event names for tool/memory/swarm interception:

// Object-style hook events (plugin system)
'session:start' | 'session:end'
'agent:pre-spawn' | 'agent:post-spawn' | 'agent:pre-terminate'
'task:pre-execute' | 'task:post-complete' | 'task:error'
'tool:pre-call' | 'tool:post-call'
'memory:pre-store' | 'memory:post-store' | 'memory:pre-retrieve'
'swarm:initialized' | 'swarm:shutdown' | 'swarm:consensus-reached'
'file:pre-read' | 'file:post-read' | 'file:pre-write'
'learning:pattern-learned' | 'learning:pattern-applied'

WorkerPool Configuration

Workers declared with new WorkerPool(name, options) join Ruflo’s 12 built-in background workers. They appear in worker/status output and can be triggered manually with worker/run.

new WorkerPool('my-worker', {
  minWorkers: 1,          // Minimum workers kept alive (default: 1)
  maxWorkers: 4,          // Maximum concurrent workers (default: 4)
  taskTimeout: 30000,     // Task timeout in ms (default: 30000)
})

Set taskTimeout conservatively. Workers that exceed the timeout are terminated and their tasks are marked failed. Long-running analysis tasks should report incremental progress via the MCP Tasks API rather than blocking a single worker.

ProviderRegistry: Adding Custom LLM Providers

Use ProviderRegistry to add LLM providers beyond the built-in set (Anthropic, OpenAI, Google, Cohere, Ollama). The registry integrates with the Thompson sampling model router and automatic failover chain.

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

const registry = new ProviderRegistry();

registry.register({
  name: 'my-provider',
  baseUrl: 'https://api.my-llm-provider.com/v1',
  models: ['my-model-fast', 'my-model-pro'],
  costPerInputToken: 0.000001,
  costPerOutputToken: 0.000003,
  authenticate: async () => ({ Authorization: `Bearer ${process.env.MY_PROVIDER_KEY}` }),
});

Once registered, the model router considers this provider in cost-optimized routing decisions and falls back to it if higher-priority providers are unavailable.

Full Plugin Reference

import {
  PluginBuilder,     // Main entry point — assembles all components
  MCPToolBuilder,    // Define typed MCP tools
  HookBuilder,       // Define lifecycle hooks with conditions
  WorkerPool,        // Background worker pool configuration
  ProviderRegistry,  // LLM provider registration
} from '@claude-flow/plugins';

For the AgentDB bridge (direct access to vector storage from within a plugin):

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

// HNSW-indexed vector storage, 150x faster search, batch operations
const bridge = new AgentDBBridge({ namespace: 'my-plugin' });
await bridge.store({ key: 'my-key', value: 'content to embed' });
const results = await bridge.search({ query: 'find similar content', limit: 5 });

CLI Commands

MCP Tools

Plugins

Build Custom Ruflo Plugins with the Plugin Builder API

Builder Components

Build Your First Plugin

MCPToolBuilder Parameter Types

HookBuilder: All 27 Hook Names

WorkerPool Configuration

ProviderRegistry: Adding Custom LLM Providers

Full Plugin Reference

Build docs developers (and LLMs) love

CLI Commands

MCP Tools

Plugins

Documentation Index

​Builder Components

​Build Your First Plugin

​MCPToolBuilder Parameter Types

​HookBuilder: All 27 Hook Names

​WorkerPool Configuration

​ProviderRegistry: Adding Custom LLM Providers

​Full Plugin Reference

Build docs developers (and LLMs) love

Builder Components

Build Your First Plugin

MCPToolBuilder Parameter Types

HookBuilder: All 27 Hook Names

WorkerPool Configuration

ProviderRegistry: Adding Custom LLM Providers

Full Plugin Reference