Claude Code Configuration - Ruflo v3.5

Ruflo v3.5 (2026-04-07) — Stable release with verified capabilities. 6,000+ commits, 314 MCP tools, 16 agent roles + custom types, 19 AgentDB controllers. Packages: @claude-flow/cli@3.5.65, claude-flow@3.5.65, ruflo@3.5.65

Behavioral Rules (Always Enforced)

• Do what has been asked; nothing more, nothing less
• NEVER create files unless they're absolutely necessary for achieving your goal
• ALWAYS prefer editing an existing file to creating a new one
• NEVER proactively create documentation files (*.md) or README files unless explicitly requested
• NEVER save working files, text/mds, or tests to the root folder
• Never continuously check status after spawning a swarm — wait for results
• ALWAYS read a file before editing it
• NEVER commit secrets, credentials, or .env files

File Organization

• NEVER save to root folder — use the directories below
• Use /src for source code files
• Use /tests for test files
• Use /docs for documentation and markdown files
• Use /config for configuration files
• Use /scripts for utility scripts
• Use /examples for example code

Project Architecture

• Follow Domain-Driven Design with bounded contexts
• Keep files under 500 lines
• Use typed interfaces for all public APIs
• Prefer TDD London School (mock-first) for new code
• Use event sourcing for state changes
• Ensure input validation at system boundaries

Key Packages

Concurrency: 1 MESSAGE = ALL RELATED OPERATIONS

• All operations MUST be concurrent/parallel in a single message
• Use Claude Code's Task tool for spawning agents, not just MCP

Mandatory patterns:

• ALWAYS batch ALL todos in ONE TodoWrite call (5-10+ minimum)
• ALWAYS spawn ALL agents in ONE message with full instructions via Task tool
• ALWAYS batch ALL file reads/writes/edits in ONE message
• ALWAYS batch ALL terminal operations in ONE Bash message
• ALWAYS batch ALL memory store/retrieve operations in ONE message

Swarm Orchestration

• MUST initialize the swarm using MCP tools when starting complex tasks
• MUST spawn concurrent agents using Claude Code's Task tool
• Never use MCP tools alone for execution — Task tool agents do the actual work

MCP + Task Tool in SAME Message

• MUST call MCP tools AND Task tool in ONE message for complex work
• Always call MCP first, then IMMEDIATELY call Task tool to spawn agents

3-Tier Model Routing (ADR-026)

• Always check for [AGENT_BOOSTER_AVAILABLE] or [TASK_MODEL_RECOMMENDATION] before spawning agents
• Use Edit tool directly when [AGENT_BOOSTER_AVAILABLE] — intent types: var-to-const, add-types, add-error-handling, async-await, add-logging, remove-console

Swarm Configuration & Anti-Drift

Anti-Drift Coding Swarm (PREFERRED DEFAULT)

• ALWAYS use hierarchical topology for coding swarms
• Keep maxAgents at 6-8 for tight coordination
• Use specialized strategy for clear role boundaries
• Use raft consensus for hive-mind (leader maintains authoritative state)
• Run frequent checkpoints via post-task hooks
• Keep shared memory namespace for all agents
• Keep task cycles short with verification gates

mcp__ruv-swarm__swarm_init({
  topology: "hierarchical",
  maxAgents: 8,
  strategy: "specialized"
})

Dual-Mode Collaboration (Claude Code + Codex)

This repository uses dual-mode orchestration to run Claude Code (🔵) and OpenAI Codex (🟢) workers in parallel with shared memory coordination. Both platforms collaborate on development tasks with cross-learning.

Why Dual-Mode?

Dual-Mode Swarm Protocol

For complex tasks, spawn both Claude and Codex workers in parallel:

// STEP 1: Initialize dual-mode swarm
mcp__ruv-swarm__swarm_init({
  topology: "hierarchical",
  maxAgents: 8,
  strategy: "specialized"
})

// STEP 2: Spawn BOTH platforms in parallel via Task tool
// 🔵 Claude Code workers (architecture, security, testing)
Task("Architect", "Design the implementation. Store design in memory namespace 'collaboration'.", "system-architect")
Task("Tester", "Write tests based on architect's design. Read from 'collaboration' namespace.", "tester")
Task("Reviewer", "Review code quality and security. Store findings in 'collaboration'.", "reviewer")

// 🟢 Codex workers (implementation, optimization)
// Spawn via CLI for Codex platform
Bash("npx claude-flow-codex dual run --worker 'codex:coder:Implement the solution based on architect design' --namespace collaboration")
Bash("npx claude-flow-codex dual run --worker 'codex:optimizer:Optimize performance based on implementation' --namespace collaboration")

// STEP 3: Coordinate via shared memory
Bash("npx claude-flow@v3alpha memory store --namespace collaboration --key 'task-context' --value '[task description]'")

Collaboration Templates (Pre-Built Pipelines)

Dual-Mode CLI Commands

# Run a collaboration template
npx claude-flow-codex dual run feature --task "Add user authentication with OAuth"
npx claude-flow-codex dual run security --target "./src"
npx claude-flow-codex dual run refactor --target "./src/legacy"

# Custom multi-platform swarm
npx claude-flow-codex dual run \
  --worker "claude:architect:Design the API structure" \
  --worker "codex:coder:Implement REST endpoints" \
  --worker "claude:tester:Write integration tests" \
  --worker "codex:reviewer:Review code quality" \
  --namespace "api-feature"

# Check collaboration status
npx claude-flow-codex dual status

# List available templates
npx claude-flow-codex dual templates

Shared Memory Coordination

All workers share state via the collaboration namespace:

# Store context for cross-platform sharing
npx claude-flow@v3alpha memory store --namespace collaboration --key "design-decisions" --value "..."

# Search for patterns across all workers
npx claude-flow@v3alpha memory search --namespace collaboration --query "authentication patterns"

# Retrieve specific findings
npx claude-flow@v3alpha memory retrieve --namespace collaboration --key "security-findings"

Cross-Platform Learning

Both platforms learn from each other's outputs:

# After successful collaboration, train patterns
npx claude-flow@v3alpha hooks post-task --task-id "dual-[id]" --success true --train-neural true

# Store successful collaboration patterns
npx claude-flow@v3alpha memory store --namespace patterns --key "dual-mode-[pattern]" --value "[what worked]"

# Transfer learnings to both platforms
npx claude-flow@v3alpha hooks transfer store --pattern "dual-collab-success"

Worker Dependency Levels

Workers execute in dependency order:

Level 0: [🔵 Architect]           # No dependencies - runs first
Level 1: [🟢 Coder, 🔵 Tester]    # Depends on Architect
Level 2: [🔵 Reviewer]            # Depends on Coder + Tester
Level 3: [🟢 Optimizer]           # Depends on Reviewer approval

Platform Strengths

Programmatic API

import { DualModeOrchestrator, CollaborationTemplates } from '@claude-flow/codex';

const orchestrator = new DualModeOrchestrator({
  namespace: 'my-feature',
  memoryBackend: 'hybrid'
});

// Use pre-built template
const workers = CollaborationTemplates.featureDevelopment('Add OAuth login');

// Run collaboration
const results = await orchestrator.runCollaboration(workers, 'Implement OAuth feature');

// Access shared memory
const designDocs = await orchestrator.getMemory('design-decisions');

Swarm Protocols & Routing

Auto-Start Swarm Protocol

When the user requests a complex task (multi-file changes, feature implementation, refactoring), immediately execute this pattern in a SINGLE message:

// STEP 1: Initialize swarm coordination via MCP (in parallel with agent spawning)
mcp__ruv-swarm__swarm_init({
  topology: "hierarchical",
  maxAgents: 8,
  strategy: "specialized"
})

// STEP 2: Spawn agents concurrently using Claude Code's Task tool
// ALL Task calls MUST be in the SAME message for parallel execution
Task("Coordinator", "You are the swarm coordinator. Initialize session, coordinate other agents via memory. Run: npx claude-flow@v3alpha hooks session-start", "hierarchical-coordinator")
Task("Researcher", "Analyze requirements and existing code patterns. Store findings in memory via hooks.", "researcher")
Task("Architect", "Design implementation approach based on research. Document decisions in memory.", "system-architect")
Task("Coder", "Implement the solution following architect's design. Coordinate via hooks.", "coder")
Task("Tester", "Write tests for the implementation. Report coverage via hooks.", "tester")
Task("Reviewer", "Review code quality and security. Document findings.", "reviewer")

// STEP 3: Batch all todos
TodoWrite({ todos: [
  {content: "Initialize swarm coordination", status: "in_progress", activeForm: "Initializing swarm"},
  {content: "Research and analyze requirements", status: "in_progress", activeForm: "Researching requirements"},
  {content: "Design architecture", status: "pending", activeForm: "Designing architecture"},
  {content: "Implement solution", status: "pending", activeForm: "Implementing solution"},
  {content: "Write tests", status: "pending", activeForm: "Writing tests"},
  {content: "Review and finalize", status: "pending", activeForm: "Reviewing code"}
]})

// STEP 4: Store swarm state in memory
mcp__claude-flow__memory_usage({
  action: "store",
  namespace: "swarm",
  key: "current-session",
  value: JSON.stringify({task: "[user's task]", agents: 6, startedAt: new Date().toISOString()})
})

Agent Routing (Anti-Drift)

Codes 1-11: hierarchical/specialized (anti-drift). Code 13: mesh/balanced

Task Complexity Detection

AUTO-INVOKE SWARM when task involves:

• Multiple files (3+)
• New feature implementation
• Refactoring across modules
• API changes with tests
• Security-related changes
• Performance optimization
• Database schema changes

SKIP SWARM for:

• Single file edits
• Simple bug fixes (1-2 lines)
• Documentation updates
• Configuration changes
• Quick questions/exploration

Project Configuration

This project is configured with Claude Flow V3 (Anti-Drift Defaults):

• Topology: hierarchical (prevents drift via central coordination)
• Max Agents: 8 (smaller team = less drift)
• Strategy: specialized (clear roles, no overlap)
• Consensus: raft (leader maintains authoritative state)
• Memory Backend: hybrid (SQLite + AgentDB)
• HNSW Indexing: Enabled (150x-12,500x faster)
• Neural Learning: Enabled (SONA)

V3 CLI Commands (26 Commands, 140+ Subcommands)

Core Commands

Advanced Commands

Quick CLI Examples

# Initialize project
npx claude-flow@v3alpha init --wizard

# Start daemon with background workers
npx claude-flow@v3alpha daemon start

# Spawn an agent
npx claude-flow@v3alpha agent spawn -t coder --name my-coder

# Initialize swarm
npx claude-flow@v3alpha swarm init --v3-mode

# Search memory (HNSW-indexed)
npx claude-flow@v3alpha memory search -q "authentication patterns"

# System diagnostics
npx claude-flow@v3alpha doctor --fix

# Security scan
npx claude-flow@v3alpha security scan --depth full

# Performance benchmark
npx claude-flow@v3alpha performance benchmark --suite all

Headless Background Instances (claude -p)

Use claude -p (print/pipe mode) to spawn headless Claude instances for parallel background work. These run non-interactively and return results to stdout.

Basic Usage

# Single headless task
claude -p "Analyze the authentication module for security issues"

# With model selection
claude -p --model haiku "Format this config file"
claude -p --model opus "Design the database schema for user management"

# With output format
claude -p --output-format json "List all TODO comments in src/"
claude -p --output-format stream-json "Refactor the error handling in api.ts"

# With budget limits
claude -p --max-budget-usd 0.50 "Run comprehensive security audit"

# With specific tools allowed
claude -p --allowedTools "Read,Grep,Glob" "Find all files that import the auth module"

# Skip permissions (sandboxed environments only)
claude -p --dangerously-skip-permissions "Fix all lint errors in src/"

Parallel Background Execution

# Spawn multiple headless instances in parallel
claude -p "Analyze src/auth/ for vulnerabilities" &
claude -p "Write tests for src/api/endpoints.ts" &
claude -p "Review src/models/ for performance issues" &
wait  # Wait for all to complete

# With results captured
SECURITY=$(claude -p "Security audit of auth module" &)
TESTS=$(claude -p "Generate test coverage report" &)
PERF=$(claude -p "Profile memory usage in workers" &)
wait
echo "$SECURITY" "$TESTS" "$PERF"

Session Continuation

# Start a task, resume later
claude -p --session-id "abc-123" "Start analyzing the codebase"
claude -p --resume "abc-123" "Continue with the test files"

# Fork a session for parallel exploration
claude -p --resume "abc-123" --fork-session "Try approach A: event sourcing"
claude -p --resume "abc-123" --fork-session "Try approach B: CQRS pattern"

Key Flags

Available Agents (60+ Types)

Core Development

coder, reviewer, tester, planner, researcher

V3 Specialized Agents

security-architect, security-auditor, memory-specialist, performance-engineer

@claude-flow/security Module

CVE remediation, input validation, path security:

• InputValidator — Zod-based validation at boundaries
• PathValidator — Path traversal prevention
• SafeExecutor — Command injection protection
• PasswordHasher — bcrypt hashing
• TokenGenerator — Secure token generation

Token Optimizer (Agent Booster)

Integrates agentic-flow optimizations for 30-50% token reduction:

import { getTokenOptimizer } from '@claude-flow/integration';
const optimizer = await getTokenOptimizer();

// Compact context (32% fewer tokens)
const ctx = await optimizer.getCompactContext("auth patterns");

// 352x faster edits = fewer retries
await optimizer.optimizedEdit(file, old, new, "typescript");

// Optimal config (100% success rate)
const config = optimizer.getOptimalConfig(agentCount);

Swarm Coordination

hierarchical-coordinator, mesh-coordinator, adaptive-coordinator, collective-intelligence-coordinator, swarm-memory-manager

Consensus & Distributed

byzantine-coordinator, raft-manager, gossip-coordinator, consensus-builder, crdt-synchronizer, quorum-manager, security-manager

Performance & Optimization

perf-analyzer, performance-benchmarker, task-orchestrator, memory-coordinator, smart-agent

GitHub & Repository

github-modes, pr-manager, code-review-swarm, issue-tracker, release-manager, workflow-automation, project-board-sync, repo-architect, multi-repo-swarm

SPARC Methodology

sparc-coord, sparc-coder, specification, pseudocode, architecture, refinement

Specialized Development

backend-dev, mobile-dev, ml-developer, cicd-engineer, api-docs, system-architect, code-analyzer, base-template-generator

Testing & Validation

tdd-london-swarm, production-validator

Agent Teams (Multi-Agent Coordination)

Claude Code's experimental Agent Teams feature is fully integrated with Claude Flow for advanced multi-agent coordination.

Enabling Agent Teams

Agent Teams is automatically enabled when you run npx claude-flow@v3alpha init. The following is added to .claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "claudeFlow": {
    "agentTeams": {
      "enabled": true,
      "teammateMode": "auto",
      "taskListEnabled": true,
      "mailboxEnabled": true
    }
  }
}

Agent Teams Components

Creating and Managing Teams

// Create a team
TeamCreate({
  team_name: "feature-dev",
  description: "Building new feature",
  agent_type: "coordinator"
})

// Create shared tasks
TaskCreate({ subject: "Design API", description: "...", activeForm: "Designing" })
TaskCreate({ subject: "Implement endpoints", description: "...", activeForm: "Implementing" })
TaskCreate({ subject: "Write tests", description: "...", activeForm: "Testing" })

// Spawn teammates (run in background for parallel work)
Task({
  prompt: "Design the API according to task #1...",
  subagent_type: "system-architect",
  team_name: "feature-dev",
  name: "architect",
  run_in_background: true
})
Task({
  prompt: "Implement endpoints from task #2...",
  subagent_type: "coder",
  team_name: "feature-dev",
  name: "developer",
  run_in_background: true
})

Agent Teams Hooks

Hook Commands

# Handle idle teammate (auto-assigns available tasks)
npx claude-flow@v3alpha hooks teammate-idle --auto-assign true

# Handle task completion (trains patterns, notifies lead)
npx claude-flow@v3alpha hooks task-completed -i task-123 --train-patterns true

# Check on team progress
TaskList

# Send message to teammate
SendMessage({
  type: "message",
  recipient: "developer",
  content: "Please prioritize the auth endpoint",
  summary: "Prioritize auth"
})

# Shutdown teammate gracefully
SendMessage({
  type: "shutdown_request",
  recipient: "developer",
  content: "Work complete, shutting down"
})

Best Practices for Agent Teams

1. Spawn teammates in background: Use run_in_background: true for parallel work
2. Create tasks first: Use TaskCreate before spawning teammates so they have work
3. Use descriptive names: Name teammates by role (architect, developer, tester)
4. Don't poll status: Wait for teammates to message back or complete
5. Graceful shutdown: Always send shutdown_request before TeamDelete
6. Clean up: Use TeamDelete after all teammates have shut down

Teammate Display Modes

V3 Hooks System (17 Hooks + 12 Workers)

Hook Categories

12 Background Workers

Essential Hook Commands

# Core hooks
npx claude-flow@v3alpha hooks pre-task --description "[task]"
npx claude-flow@v3alpha hooks post-task --task-id "[id]" --success true
npx claude-flow@v3alpha hooks post-edit --file "[file]" --train-patterns

# Session management
npx claude-flow@v3alpha hooks session-start --session-id "[id]"
npx claude-flow@v3alpha hooks session-end --export-metrics true
npx claude-flow@v3alpha hooks session-restore --session-id "[id]"

# Intelligence routing
npx claude-flow@v3alpha hooks route --task "[task]"
npx claude-flow@v3alpha hooks explain --topic "[topic]"

# Neural learning
npx claude-flow@v3alpha hooks pretrain --model-type moe --epochs 10
npx claude-flow@v3alpha hooks build-agents --agent-types coder,tester

# Background workers
npx claude-flow@v3alpha hooks worker list
npx claude-flow@v3alpha hooks worker dispatch --trigger audit
npx claude-flow@v3alpha hooks worker status

Intelligence System (RuVector)

V3 includes the RuVector Intelligence System:

• SONA: Self-Optimizing Neural Architecture (<0.05ms adaptation)
• MoE: Mixture of Experts for specialized routing
• HNSW: 150x-12,500x faster pattern search
• EWC++: Elastic Weight Consolidation (prevents forgetting)
• Flash Attention: 2.49x-7.47x speedup

The 4-step intelligence pipeline:

1. RETRIEVE — Fetch relevant patterns via HNSW
2. JUDGE — Evaluate with verdicts (success/failure)
3. DISTILL — Extract key learnings via LoRA
4. CONSOLIDATE — Prevent catastrophic forgetting via EWC++

Embeddings Package (v3.0.0-alpha.12)

Features:

• sql.js: Cross-platform SQLite persistent cache (WASM, no native compilation)
• Document chunking: Configurable overlap and size
• Normalization: L2, L1, min-max, z-score
• Hyperbolic embeddings: Poincare ball model for hierarchical data
• 75x faster: With agentic-flow ONNX integration
• Neural substrate: Integration with RuVector

Hive-Mind Consensus

Topologies

• hierarchical — Queen controls workers directly
• mesh — Fully connected peer network
• hierarchical-mesh — Hybrid (recommended)
• adaptive — Dynamic based on load

Consensus Strategies

• byzantine — BFT (tolerates f < n/3 faulty)
• raft — Leader-based (tolerates f < n/2)
• gossip — Epidemic for eventual consistency
• crdt — Conflict-free replicated data types
• quorum — Configurable quorum-based

V3 Performance Targets

Environment Variables

# Configuration
CLAUDE_FLOW_CONFIG=./claude-flow.config.json
CLAUDE_FLOW_LOG_LEVEL=info

# Provider API Keys
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=...

# MCP Server
CLAUDE_FLOW_MCP_PORT=3000
CLAUDE_FLOW_MCP_HOST=localhost
CLAUDE_FLOW_MCP_TRANSPORT=stdio

# Memory
CLAUDE_FLOW_MEMORY_BACKEND=hybrid
CLAUDE_FLOW_MEMORY_PATH=./data/memory

Doctor Health Checks

Run npx claude-flow@v3alpha doctor to check:

• Node.js version (20+)
• npm version (9+)
• Git installation
• Config file validity
• Daemon status
• Memory database
• API keys
• MCP servers
• Disk space
• TypeScript installation

Quick Setup

# Add MCP servers
claude mcp add claude-flow npx claude-flow@v3alpha mcp start
claude mcp add ruv-swarm npx ruv-swarm mcp start  # Optional
claude mcp add flow-nexus npx flow-nexus@latest mcp start  # Optional

# Start daemon
npx claude-flow@v3alpha daemon start

# Run doctor
npx claude-flow@v3alpha doctor --fix

Claude Code vs MCP Tools

Claude Code Handles ALL EXECUTION:

• Task tool: Spawn and run agents concurrently
• File operations (Read, Write, Edit, MultiEdit, Glob, Grep)
• Code generation and programming
• Bash commands and system operations
• TodoWrite and task management
• Git operations

MCP Tools ONLY COORDINATE:

• Swarm initialization (topology setup)

• Agent type definitions

• Task orchestration

• Memory management

• Neural features

• Performance tracking

• Keep MCP for coordination strategy only — use Claude Code's Task tool for real execution

Claude Code ↔ AgentDB Memory Bridge

Claude Code's auto-memory (~/.claude/projects/*/memory/*.md) is bridged to AgentDB with ONNX vector embeddings for semantic search.

MCP Tools

Auto-Import on Session Start

The SessionStart hook automatically imports current project's memories into AgentDB. For manual import of all projects:

# Via MCP tool (from Claude Code)
memory_import_claude({ allProjects: true })

# Via helper hook (from terminal)
node .claude/helpers/auto-memory-hook.mjs import-all

Unified Search

Search across both Claude Code memories and AgentDB entries:

# Via MCP tool
memory_search_unified({ query: "authentication security", limit: 5 })

# Results include source attribution: claude-code, auto-memory, or agentdb

Intelligence Pipeline

Publishing to npm

Publishing Rules

• MUST publish ALL THREE packages when publishing CLI changes: @claude-flow/cli, claude-flow, AND ruflo
• MUST update ALL dist-tags for ALL THREE packages after publishing
• Publish order: @claude-flow/cli first, then claude-flow (umbrella), then ruflo (alias umbrella)
• MUST run verification for ALL THREE before telling user publishing is complete

# STEP 1: Build and publish CLI
cd v3/@claude-flow/cli
npm version 3.0.0-alpha.XXX --no-git-tag-version
npm run build
npm publish --tag alpha
npm dist-tag add @claude-flow/cli@3.0.0-alpha.XXX latest

# STEP 2: Publish claude-flow umbrella
cd /workspaces/claude-flow
npm version 3.0.0-alpha.XXX --no-git-tag-version
npm publish --tag v3alpha

# STEP 3: Update ALL claude-flow umbrella tags (CRITICAL - DON'T SKIP!)
npm dist-tag add claude-flow@3.0.0-alpha.XXX latest
npm dist-tag add claude-flow@3.0.0-alpha.XXX alpha

# STEP 4: Publish ruflo umbrella (CRITICAL - DON'T FORGET!)
cd /workspaces/claude-flow/ruflo
npm version 3.0.0-alpha.XXX --no-git-tag-version
npm publish --tag alpha
npm dist-tag add ruflo@3.0.0-alpha.XXX latest

Verification (run before telling user):

npm view @claude-flow/cli dist-tags --json
npm view claude-flow dist-tags --json
npm view ruflo dist-tags --json
# ALL THREE packages need: alpha AND latest pointing to newest version

All Tags That Must Be Updated

• Never forget the ruflo package — it's a thin wrapper users run via npx ruflo@alpha
• Never forget the umbrella alpha tag — users run npx claude-flow@alpha
• ruflo source is in /ruflo/ — it depends on @claude-flow/cli

Plugin Registry Maintenance (IPFS/Pinata)

The plugin registry is stored on IPFS via Pinata for decentralized, immutable distribution.

Registry Location

• Current CID: Stored in v3/@claude-flow/cli/src/plugins/store/discovery.ts
• Gateway: https://gateway.pinata.cloud/ipfs/{CID}
• Format: JSON with plugin metadata, categories, featured/trending lists

Required Environment Variables

Add to .env (NEVER commit actual values):

PINATA_API_KEY=your-api-key
PINATA_API_SECRET=your-api-secret
PINATA_API_JWT=your-jwt-token

Plugin Registry Operations

Adding a New Plugin to Registry

1. Fetch current registry:

curl -s "https://gateway.pinata.cloud/ipfs/$(grep LIVE_REGISTRY_CID v3/@claude-flow/cli/src/plugins/store/discovery.ts | cut -d"'" -f2)" > /tmp/registry.json

2. Add plugin entry to the plugins array:

{
  "id": "@claude-flow/your-plugin",
  "name": "@claude-flow/your-plugin",
  "displayName": "Your Plugin",
  "description": "Plugin description",
  "version": "1.0.0-alpha.1",
  "size": 100000,
  "checksum": "sha256:abc123",
  "author": {"id": "claude-flow-team", "displayName": "Claude Flow Team", "verified": true},
  "license": "MIT",
  "categories": ["official"],
  "tags": ["your", "tags"],
  "downloads": 0,
  "rating": 5,
  "lastUpdated": "2026-01-25T00:00:00.000Z",
  "minClaudeFlowVersion": "3.0.0",
  "type": "integration",
  "hooks": [],
  "commands": [],
  "permissions": ["memory"],
  "exports": ["YourExport"],
  "verified": true,
  "trustLevel": "official"
}

3. Update counts and arrays:

   • Increment totalPlugins
   • Add to official array
   • Add to featured/newest if applicable
   • Update category pluginCount

4. Upload to Pinata (read credentials from .env):

# Source credentials from .env
PINATA_JWT=$(grep "^PINATA_API_JWT=" .env | cut -d'=' -f2-)

# Upload updated registry
curl -X POST "https://api.pinata.cloud/pinning/pinJSONToIPFS" \
  -H "Authorization: Bearer $PINATA_JWT" \
  -H "Content-Type: application/json" \
  -d @/tmp/registry.json

5. Update discovery.ts with new CID:

export const LIVE_REGISTRY_CID = 'NEW_CID_FROM_PINATA';

6. Also update demo registry in discovery.ts demoPluginRegistry for offline fallback

Security Rules

• NEVER hardcode API keys in scripts or source files
• NEVER commit .env (already in .gitignore)
• Always source credentials from environment at runtime
• Always delete temporary scripts after one-time uploads

Verification

# Verify new registry is accessible
curl -s "https://gateway.pinata.cloud/ipfs/{NEW_CID}" | jq '.totalPlugins'

Optional Plugins (20 Available)

Plugins are distributed via IPFS and can be installed with the CLI. Browse and install from the official registry:

# List all available plugins
npx claude-flow@v3alpha plugins list

# Install a plugin
npx claude-flow@v3alpha plugins install @claude-flow/plugin-name

# Enable/disable
npx claude-flow@v3alpha plugins enable @claude-flow/plugin-name
npx claude-flow@v3alpha plugins disable @claude-flow/plugin-name

Core Plugins

Integration Plugins

Domain-Specific Plugins

Plugin Development

# Create a new plugin from template
npx claude-flow@v3alpha plugins create my-plugin

# Test locally
npx claude-flow@v3alpha plugins install ./path/to/my-plugin

# Publish to registry (requires Pinata credentials)
npx claude-flow@v3alpha plugins publish

Registry source: IPFS via Pinata (QmXbfEAaR7D2Ujm4GAkbwcGZQMHqAMpwDoje4583uNP834)

Support

• Documentation: https://github.com/ruvnet/claude-flow
• Issues: https://github.com/ruvnet/claude-flow/issues

Remember: Claude Flow coordinates, Claude Code creates!

🌊 RuFlo v3.5: Enterprise AI Orchestration Platform

Multi-agent AI orchestration for Claude Code

Deploy 16 specialized agent roles + custom types in coordinated swarms with self-learning capabilities, fault-tolerant consensus, and enterprise-grade security.

Why Ruflo? Claude Flow is now Ruflo — named by Ruv, who loves Rust, flow states, and building things that feel inevitable. The "Ru" is the Ruv. The "flo" is the flow. Underneath, WASM kernels written in Rust power the policy engine, embeddings, and proof system. 6,000+ commits later, this is v3.5.

Getting into the Flow

Ruflo is a comprehensive AI agent orchestration framework that transforms Claude Code into a powerful multi-agent development platform. It enables teams to deploy, coordinate, and optimize specialized AI agents working together on complex software engineering tasks.

Self-Learning/Self-Optimizing Agent Architecture

User → Ruflo (CLI/MCP) → Router → Swarm → Agents → Memory → LLM Providers
                       ↑                          ↓
                       └──── Learning Loop ←──────┘

flowchart TB
    subgraph USER["👤 User Layer"]
        U[User]
    end

    subgraph ENTRY["🚪 Entry Layer"]
        CLI[CLI / MCP Server]
        AID[AIDefence Security]
    end

    subgraph ROUTING["🧭 Routing Layer"]
        QL[Q-Learning Router]
        MOE[MoE - 8 Experts]
        SK[Skills - 130+]
        HK[Hooks - 27]
    end

    subgraph SWARM["🐝 Swarm Coordination"]
        TOPO[Topologies<br/>mesh/hier/ring/star]
        CONS[Consensus<br/>Raft/BFT/Gossip]
        CLM[Claims<br/>Human-Agent Coord]
    end

    subgraph AGENTS["🤖 100+ Agents"]
        AG1[coder]
        AG2[tester]
        AG3[reviewer]
        AG4[architect]
        AG5[security]
        AG6[...]
    end

    subgraph RESOURCES["📦 Resources"]
        MEM[(Memory<br/>AgentDB)]
        PROV[Providers<br/>Claude/GPT/Gemini/Ollama]
        WORK[Workers - 12<br/>ultralearn/audit/optimize]
    end

    subgraph RUVECTOR["🧠 RuVector Intelligence Layer"]
        direction TB
        subgraph ROW1[" "]
            SONA[SONA<br/>Self-Optimize<br/>&lt;0.05ms]
            EWC[EWC++<br/>No Forgetting]
            FLASH[Flash Attention<br/>2.49-7.47x]
        end
        subgraph ROW2[" "]
            HNSW[HNSW<br/>HNSW-indexed]
            RB[ReasoningBank<br/>Pattern Store]
            HYP[Hyperbolic<br/>Poincaré]
        end
        subgraph ROW3[" "]
            LORA[LoRA/Micro<br/>low-rank adaptation]
            QUANT[Int8 Quant<br/>3.92x memory]
            RL[9 RL Algos<br/>Q/SARSA/PPO/DQN]
        end
    end

    subgraph LEARNING["🔄 Learning Loop"]
        L1[RETRIEVE] --> L2[JUDGE] --> L3[DISTILL] --> L4[CONSOLIDATE] --> L5[ROUTE]
    end

    U --> CLI
    CLI --> AID
    AID --> QL & MOE & SK & HK
    QL & MOE & SK & HK --> TOPO & CONS & CLM
    TOPO & CONS & CLM --> AG1 & AG2 & AG3 & AG4 & AG5 & AG6
    AG1 & AG2 & AG3 & AG4 & AG5 & AG6 --> MEM & PROV & WORK
    MEM --> SONA & EWC & FLASH
    SONA & EWC & FLASH --> HNSW & RB & HYP
    HNSW & RB & HYP --> LORA & QUANT & RL
    LORA & QUANT & RL --> L1
    L5 -.->|loops back| QL

    style RUVECTOR fill:#1a1a2e,stroke:#e94560,stroke-width:2px
    style LEARNING fill:#0f3460,stroke:#e94560,stroke-width:2px
    style USER fill:#16213e,stroke:#0f3460
    style ENTRY fill:#1a1a2e,stroke:#0f3460
    style ROUTING fill:#1a1a2e,stroke:#0f3460
    style SWARM fill:#1a1a2e,stroke:#0f3460
    style AGENTS fill:#1a1a2e,stroke:#0f3460
    style RESOURCES fill:#1a1a2e,stroke:#0f3460

RuVector Components (included with Ruflo):

# Use RuVector via Ruflo
npx ruflo@latest hooks intelligence --status

Get Started Fast

# One-line install (recommended)
curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash

# Or full setup with MCP + diagnostics
curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash -s -- --full

# Or via npx
npx ruflo@latest init --wizard

New to Ruflo? You don't need to learn 310+ MCP tools or 26 CLI commands. After running init, just use Claude Code normally — the hooks system automatically routes tasks to the right agents, learns from successful patterns, and coordinates multi-agent work in the background. The advanced tools exist for fine-grained control when you need it.

Key Capabilities

🤖 100+ Specialized Agents - Ready-to-use AI agents for coding, code review, testing, security audits, documentation, and DevOps. Each agent is optimized for its specific role.

🐝 Coordinated Agent Teams - Run unlimited agents simultaneously in organized swarms. Agents spawn sub-workers, communicate, share context, and divide work automatically using hierarchical (queen/workers) or mesh (peer-to-peer) patterns.

🧠 Learns From Your Workflow - The system remembers what works. Successful patterns are stored and reused, routing similar tasks to the best-performing agents. Gets smarter over time.

🔌 Works With Any LLM - Switch between Claude, GPT, Gemini, Cohere, or local models like Llama. Automatic failover if one provider is unavailable. Smart routing picks the cheapest option that meets quality requirements.

⚡ Plugs Into Claude Code - Native integration via MCP (Model Context Protocol). Use ruflo commands directly in your Claude Code sessions with full tool access.

🔒 Production-Ready Security - Built-in protection against prompt injection, input validation, path traversal prevention, command injection blocking, and safe credential handling.

🧩 Extensible Plugin System - Add custom capabilities with the plugin SDK. Create workers, hooks, providers, and security modules. Share plugins via the decentralized IPFS marketplace.

A multi-purpose Agent Tool Kit

Every request flows through four layers: from your CLI or Claude Code interface, through intelligent routing, to specialized agents, and finally to LLM providers for reasoning.

Agents organize into swarms led by queens that coordinate work, prevent drift, and reach consensus on decisions—even when some agents fail.

Hive Mind Capabilities:

• 🐝 Queen Types: Strategic (planning), Tactical (execution), Adaptive (optimization)
• 👷 8 Worker Types: Researcher, Coder, Analyst, Tester, Architect, Reviewer, Optimizer, Documenter
• 🗳️ 3 Consensus Algorithms: Majority, Weighted (Queen 3x), Byzantine (f < n/3)
• 🧠 Collective Memory: Shared knowledge, LRU cache, SQLite persistence with WAL
• ⚡ Performance: Fast batch spawning with parallel agent coordination

The system stores successful patterns in vector memory, builds a knowledge graph for structural understanding, learns from outcomes via neural networks, and adapts routing based on what works best.

Skip expensive LLM calls for simple tasks using WebAssembly transforms, and compress tokens to reduce API costs by 30-50%.

Background daemons handle security audits, performance optimization, and session persistence automatically while you work.

Smart routing skips expensive LLM calls when possible. Simple edits use WASM (free), medium tasks use cheaper models. This can extend your Claude Code usage by 250% or save significantly on direct API costs.

Agent Booster uses WebAssembly to handle simple code transformations without calling the LLM at all. When the hooks system detects a simple task, it routes directly to Agent Booster for instant results.

Supported Transform Intents:

Hook Signals:

When you see these in hook output, the system is telling you how to optimize:

# Agent Booster available - skip LLM entirely
[AGENT_BOOSTER_AVAILABLE] Intent: var-to-const
→ Use Edit tool directly, instant (regex-based, no LLM call) than LLM

# Model recommendation for Task tool
[TASK_MODEL_RECOMMENDATION] Use model="haiku"
→ Pass model="haiku" to Task tool for cost savings

Performance:

The Token Optimizer integrates agentic-flow optimizations to reduce API costs by compressing context and caching results.

Savings Breakdown:

Usage:

import { getTokenOptimizer } from '@claude-flow/integration';
const optimizer = await getTokenOptimizer();

// Get compact context (32% fewer tokens)
const ctx = await optimizer.getCompactContext("auth patterns");

// Optimized edit (instant (regex-based, no LLM call) for simple transforms)
await optimizer.optimizedEdit(file, oldStr, newStr, "typescript");

// Optimal config for swarm (100% success rate)
const config = optimizer.getOptimalConfig(agentCount);

Complex swarms can drift from their original goals. Ruflo V3 includes anti-drift defaults that prevent agents from going off-task.

Recommended Configuration:

// Anti-drift defaults (ALWAYS use for coding tasks)
swarm_init({
  topology: "hierarchical",  // Single coordinator enforces alignment
  maxAgents: 8,              // Smaller team = less drift surface
  strategy: "specialized"    // Clear roles reduce ambiguity
})

Why This Prevents Drift:

Additional Anti-Drift Measures:

• Frequent checkpoints via post-task hooks
• Shared memory namespace for all agents
• Short task cycles with verification gates
• Hierarchical coordinator reviews all outputs

Task → Agent Routing (Anti-Drift):

Claude Code: With vs Without Ruflo

Quick Start

Prerequisites

• Node.js 20+ (required)
• npm 9+ / pnpm / bun package manager

IMPORTANT: Claude Code must be installed first:

# 1. Install Claude Code globally
npm install -g @anthropic-ai/claude-code

# 2. (Optional) Skip permissions check for faster setup
claude --dangerously-skip-permissions

Installation

One-Line Install (Recommended)

# curl-style installer with progress display
curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash

# Full setup (global + MCP + diagnostics)
curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash -s -- --full

Examples:

# Minimal global install (fastest)
curl ... | bash -s -- --global --minimal

# With MCP auto-setup
curl ... | bash -s -- --global --setup-mcp

# Full setup with diagnostics
curl ... | bash -s -- --full

Speed:

npm/npx Install

# Quick start (no install needed)
npx ruflo@latest init

# Or install globally
npm install -g ruflo@latest
ruflo init

# With Bun (faster)
bunx ruflo@latest init

Install Profiles

# Minimal install (skip ML/embeddings)
npm install -g ruflo@latest --omit=optional

Ruflo supports both Claude Code and OpenAI Codex CLI via the @claude-flow/codex package, following the Agentics Foundation standard.

Quick Start for Codex

# Initialize for Codex CLI (creates AGENTS.md instead of CLAUDE.md)
npx ruflo@latest init --codex

# Full Codex setup with all 137+ skills
npx ruflo@latest init --codex --full

# Initialize for both platforms (dual mode)
npx ruflo@latest init --dual

Platform Comparison

Key Concept: Execution Model

┌─────────────────────────────────────────────────────────────────┐
│  CLAUDE-FLOW = ORCHESTRATOR (tracks state, stores memory)       │
│  CODEX = EXECUTOR (writes code, runs commands, implements)      │
└─────────────────────────────────────────────────────────────────┘

Codex does the work. Claude-flow coordinates and learns.

Dual-Mode Integration (Claude Code + Codex)

Run Claude Code for interactive development and spawn headless Codex workers for parallel background tasks:

┌─────────────────────────────────────────────────────────────────┐
│  CLAUDE CODE (interactive)  ←→  CODEX WORKERS (headless)        │
│  - Main conversation         - Parallel background execution    │
│  - Complex reasoning         - Bulk code generation            │
│  - Architecture decisions    - Test execution                   │
│  - Final integration         - File processing                  │
└─────────────────────────────────────────────────────────────────┘

# Spawn parallel Codex workers from Claude Code
claude -p "Analyze src/auth/ for security issues" --session-id "task-1" &
claude -p "Write unit tests for src/api/" --session-id "task-2" &
claude -p "Optimize database queries in src/db/" --session-id "task-3" &
wait  # Wait for all to complete

Dual-Mode CLI Commands (NEW)

# List collaboration templates
npx @claude-flow/codex dual templates

# Run feature development swarm (architect → coder → tester → reviewer)
npx @claude-flow/codex dual run --template feature --task "Add user auth"

# Run security audit swarm (scanner → analyzer → fixer)
npx @claude-flow/codex dual run --template security --task "src/auth/"

# Run refactoring swarm (analyzer → planner → refactorer → validator)
npx @claude-flow/codex dual run --template refactor --task "src/legacy/"

Pre-Built Collaboration Templates

MCP Integration for Codex

When you run init --codex, the MCP server is automatically registered:

# Verify MCP is registered
codex mcp list

# If not present, add manually:
codex mcp add ruflo -- npx ruflo mcp start

Self-Learning Workflow

1. LEARN:   memory_search(query="task keywords") → Find similar patterns
2. COORD:   swarm_init(topology="hierarchical") → Set up coordination
3. EXECUTE: YOU write code, run commands       → Codex does real work
4. REMEMBER: memory_store(key, value, namespace="patterns") → Save for future

The Intelligence Loop (ADR-050) automates this cycle through hooks. Each session automatically:

• Builds a knowledge graph from memory entries (PageRank + Jaccard similarity)
• Injects ranked context into every route decision
• Tracks edit patterns and generates new insights
• Boosts confidence for useful patterns, decays unused ones
• Saves snapshots so you can track improvement with node .claude/helpers/hook-handler.cjs stats

MCP Tools for Learning

137+ Skills Available

Vector Search Details

• Embedding Dimensions: 384
• Search Algorithm: HNSW (sub-millisecond)
• Similarity Scoring: 0-1 (higher = better)
  • Score > 0.7: Strong match, use pattern
  • Score 0.5-0.7: Partial match, adapt
  • Score < 0.5: Weak match, create new

Basic Usage

# Initialize project
npx ruflo@latest init

# Start MCP server for Claude Code integration
npx ruflo@latest mcp start

# Spawn a coding agent
npx ruflo@latest agent spawn -t coder --name my-coder

# Launch a hive-mind swarm with an objective
npx ruflo@latest hive-mind spawn "Implement user authentication"

# List available agent types
npx ruflo@latest agent list

Upgrading

# Update helpers and statusline (preserves your data)
npx ruflo@latest init upgrade

# Update AND add any missing skills/agents/commands
npx ruflo@latest init upgrade --add-missing

The --add-missing flag automatically detects and installs new skills, agents, and commands that were added in newer versions, without overwriting your existing customizations.

Claude Code MCP Integration

Add ruflo as an MCP server for seamless integration:

# Add ruflo MCP server to Claude Code
claude mcp add ruflo -- npx -y ruflo@latest mcp start

# Verify installation
claude mcp list

Once added, Claude Code can use all 313 ruflo MCP tools directly:

• swarm_init - Initialize agent swarms
• agent_spawn - Spawn specialized agents
• memory_search - Search patterns with HNSW vector search
• hooks_route - Intelligent task routing
• And 255+ more tools...

What is it exactly? Agents that learn, build and work perpetually.

Ruflo v3 introduces self-learning neural capabilities that no other agent orchestration framework offers. While competitors require manual agent configuration and static routing, Ruflo learns from every task execution, prevents catastrophic forgetting of successful patterns, and intelligently routes work to specialized experts.

🧠 Neural & Learning

💾 Memory & Embeddings

🐝 Swarm & Coordination

🔧 Developer Experience

🛡️ Security & Platform

Comparison updated February 2026. Feature availability based on public documentation.

What makes Ruflo different from other agent frameworks? These 10 capabilities work together to create a system that learns from experience, runs efficiently on any hardware, and keeps working even when things go wrong.

Not every task needs the most powerful (and expensive) model. Ruflo analyzes each request and automatically routes it to the cheapest handler that can do the job well. Simple code transforms skip the LLM entirely using WebAssembly. Medium tasks use faster, cheaper models. Only complex architecture decisions use Opus.

Cost & Usage Benefits:

Routing Tiers:

Routing: Q-learning with epsilon-greedy exploration, sub-millisecond decision latency

Complex projects fail when implementation drifts from the original plan. Ruflo solves this with a spec-first approach: define your architecture through ADRs (Architecture Decision Records), organize code into DDD bounded contexts, and let the system enforce compliance as agents work. The result is implementations that match specifications — even across multi-agent swarms working in parallel.

How It Prevents Drift:

Specification Features:

DDD Bounded Contexts:

┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│    Core     │  │   Memory    │  │  Security   │
│  Agents,    │  │  AgentDB,   │  │  AIDefence, │
│  Swarms,    │  │  HNSW,      │  │  Validation │
│  Tasks      │  │  Cache      │  │  CVE Fixes  │
└─────────────┘  └─────────────┘  └─────────────┘
┌─────────────┐  ┌─────────────┐
│ Integration │  │Coordination │
│ agentic-    │  │  Consensus, │
│ flow,MCP    │  │  Hive-Mind  │
└─────────────┘  └─────────────┘

Key ADRs:

• ADR-001: agentic-flow@alpha as foundation (eliminates 10,000+ duplicate lines)
• ADR-006: Unified Memory Service with AgentDB
• ADR-008: Vitest testing framework (10x faster than Jest)
• ADR-009: Hybrid Memory Backend (SQLite + HNSW)
• ADR-026: Intelligent 3-tier model routing
• ADR-048: Auto Memory Bridge (Claude Code ↔ AgentDB bidirectional sync)
• ADR-049: Self-Learning Memory with GNN (LearningBridge, MemoryGraph, AgentMemoryScope)

🏗️ Architecture Diagrams

flowchart TB
    subgraph User["👤 User Layer"]
        CC[Claude Code]
        CLI[CLI Commands]
    end

    subgraph Orchestration["🎯 Orchestration Layer"]
        MCP[MCP Server]
        Router[Intelligent Router]
        Hooks[Self-Learning Hooks]
    end

    subgraph Agents["🤖 Agent Layer"]
        Queen[Queen Coordinator]
        Workers[100+ Specialized Agents]
        Swarm[Swarm Manager]
    end

    subgraph Intelligence["🧠 Intelligence Layer"]
        SONA[SONA Learning]
        MoE[Mixture of Experts]
        HNSW[HNSW Vector Search]
    end

    subgraph Providers["☁️ Provider Layer"]
        Anthropic[Anthropic]
        OpenAI[OpenAI]
        Google[Google]
        Ollama[Ollama]
    end

    CC --> MCP
    CLI --> MCP
    MCP --> Router
    Router --> Hooks
    Hooks --> Queen
    Queen --> Workers
    Queen --> Swarm
    Workers --> Intelligence
    Intelligence --> Providers

sequenceDiagram
    participant U as User
    participant R as Router
    participant H as Hooks
    participant A as Agent Pool
    participant M as Memory
    participant P as Provider

    U->>R: Submit Task
    R->>H: pre-task hook
    H->>H: Analyze complexity

    alt Simple Task
        H->>A: Agent Booster (WASM)
        A-->>U: Result (<1ms)
    else Medium Task
        H->>A: Spawn Haiku Agent
        A->>M: Check patterns
        M-->>A: Cached context
        A->>P: LLM Call
        P-->>A: Response
        A->>H: post-task hook
        H->>M: Store patterns
        A-->>U: Result
    else Complex Task
        H->>A: Spawn Swarm
        A->>A: Coordinate agents
        A->>P: Multiple LLM calls
        P-->>A: Responses
        A->>H: post-task hook
        A-->>U: Result
    end

flowchart LR
    subgraph Input["📥 Input"]
        Query[Query/Pattern]
        Insight[New Insight]
    end

    subgraph Processing["⚙️ Processing"]
        Embed[ONNX Embeddings]
        Normalize[Normalization]
        Learn[LearningBridge<br/>SONA + ReasoningBank]
    end

    subgraph Storage["💾 Storage"]
        HNSW[(HNSW Index<br/>150x faster)]
        SQLite[(SQLite Cache)]
        AgentDB[(AgentDB)]
        Graph[MemoryGraph<br/>PageRank + Communities]
    end

    subgraph Retrieval["🔍 Retrieval"]
        Vector[Vector Search]
        Semantic[Semantic Match]
        Rank[Graph-Aware Ranking]
        Results[Top-K Results]
    end

    Query --> Embed
    Embed --> Normalize
    Normalize --> HNSW
    Normalize --> SQLite
    Insight --> Learn
    Learn --> AgentDB
    AgentDB --> Graph
    HNSW --> Vector
    SQLite --> Vector
    AgentDB --> Semantic
    Vector --> Rank
    Semantic --> Rank
    Graph --> Rank
    Rank --> Results

Self-Learning Memory (ADR-049):

Ruflo V3 integrates AgentDB v3 (3.0.0-alpha.10) providing 20+ memory controllers accessible via MCP tools and the CLI.

Core Memory:

Intelligence:

Causal & Explainable:

Security & Integrity:

Optimization:

MCP Tool Examples:

# Store to hierarchical memory
agentdb_hierarchical-store --key "auth-pattern" --value "JWT refresh" --tier "semantic"

# Recall from memory tiers
agentdb_hierarchical-recall --query "authentication" --topK 5

# Run memory consolidation
agentdb_consolidate

# Batch insert
agentdb_batch --operation insert --entries '[{"key":"k1","value":"v1"}]'

# Synthesize context
agentdb_context-synthesize --query "error handling patterns"

# Semantic routing
agentdb_semantic-route --input "fix auth bug in login"

Hierarchical Memory Tiers:

┌─────────────────────────────────────────────┐
│  Working Memory                             │  ← Active context, fast access
│  Size-based eviction (1MB limit)            │
├─────────────────────────────────────────────┤
│  Episodic Memory                            │  ← Recent patterns, moderate retention
│  Importance × retention score ranking       │
├─────────────────────────────────────────────┤
│  Semantic Memory                            │  ← Consolidated knowledge, persistent
│  Promoted from episodic via consolidation   │
└─────────────────────────────────────────────┘

flowchart TB
    subgraph Hierarchical["👑 Hierarchical (Default)"]
        Q1[Queen] --> W1[Worker 1]
        Q1 --> W2[Worker 2]
        Q1 --> W3[Worker 3]
    end

    subgraph Mesh["🕸️ Mesh"]
        M1[Agent] <--> M2[Agent]
        M2 <--> M3[Agent]
        M3 <--> M1[Agent]
    end

    subgraph Ring["💍 Ring"]
        R1[Agent] --> R2[Agent]
        R2 --> R3[Agent]
        R3 --> R1
    end

    subgraph Star["⭐ Star"]
        S1[Hub] --> S2[Agent]
        S1 --> S3[Agent]
        S1 --> S4[Agent]
    end

flowchart TB
    subgraph Input["📥 Input Validation"]
        Req[Request] --> Scan[AIDefence Scan]
        Scan --> PII[PII Detection]
        Scan --> Inject[Injection Check]
        Scan --> Jailbreak[Jailbreak Detection]
    end

    subgraph Decision["⚖️ Decision"]
        PII --> Risk{Risk Level}
        Inject --> Risk
        Jailbreak --> Risk
    end

    subgraph Action["🎬 Action"]
        Risk -->|Safe| Allow[✅ Allow]
        Risk -->|Warning| Sanitize[🧹 Sanitize]
        Risk -->|Threat| Block[⛔ Block]
    end

    subgraph Learn["📚 Learning"]
        Allow --> Log[Log Pattern]
        Sanitize --> Log
        Block --> Log
        Log --> Update[Update Model]
    end

🔌 Setup & Configuration

Connect Ruflo to your development environment.

Ruflo runs as an MCP (Model Context Protocol) server, allowing you to connect it to any MCP-compatible AI client. This means you can use Ruflo's 100+ agents, swarm coordination, and self-learning capabilities from Claude Desktop, VS Code, Cursor, Windsurf, ChatGPT, and more.

Quick Add Command

# Start Ruflo MCP server in any environment
npx ruflo@latest mcp start

Config Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Access: Claude → Settings → Developers → Edit Config

{
  "mcpServers": {
    "ruflo": {
      "command": "npx",
      "args": ["ruflo@latest", "mcp", "start"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Restart Claude Desktop after saving. Look for the MCP indicator (hammer icon) in the input box.

Sources: Claude Help Center, Anthropic Desktop Extensions

# Add via CLI (recommended)
claude mcp add ruflo -- npx ruflo@latest mcp start

# Or add with environment variables
claude mcp add ruflo \
  --env ANTHROPIC_API_KEY=sk-ant-... \
  -- npx ruflo@latest mcp start

# Verify installation
claude mcp list

Sources: Claude Code MCP Docs

Requires: VS Code 1.102+ (MCP support is GA)

Method 1: Command Palette

1. Press Cmd+Shift+P (Mac) / Ctrl+Shift+P (Windows)
2. Run MCP: Add Server
3. Enter server details

Method 2: Workspace Config

Create .vscode/mcp.json in your project:

{
  "mcpServers": {
    "ruflo": {
      "command": "npx",
      "args": ["ruflo@latest", "mcp", "start"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Sources: VS Code MCP Docs, MCP Integration Guides

Method 1: One-Click (if available in Cursor MCP marketplace)

Method 2: Manual Config

Create .cursor/mcp.json in your project (or global config):

{
  "mcpServers": {
    "ruflo": {
      "command": "npx",
      "args": ["ruflo@latest", "mcp", "start"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Important: Cursor must be in Agent Mode (not Ask Mode) to access MCP tools. Cursor supports up to 40 MCP tools.

Sources: Cursor MCP Docs, Cursor Directory

Config Location: ~/.codeium/windsurf/mcp_config.json

Access: Windsurf Settings → Cascade → MCP Servers, or click the hammer icon in Cascade panel

{
  "mcpServers": {
    "ruflo": {
      "command": "npx",
      "args": ["ruflo@latest", "mcp", "start"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Click Refresh in the MCP settings to connect. Windsurf supports up to 100 MCP tools.

Sources: Windsurf MCP Tutorial, Windsurf Cascade Docs

Requires: ChatGPT Pro or Plus subscription with Developer Mode enabled

Setup:

1. Go to Settings → Connectors → Advanced
2. Enable Developer Mode (beta)
3. Add your MCP Server in the Connectors tab

Remote Server Setup:

For ChatGPT, you need a remote MCP server (not local stdio). Deploy ruflo to a server with HTTP transport:

# Start with HTTP transport
npx ruflo@latest mcp start --transport http --port 3000

Then add the server URL in ChatGPT Connectors settings.

Sources: OpenAI MCP Docs, Docker MCP for ChatGPT

Google AI Studio supports MCP natively since May 2025, with managed MCP servers for Google services (Maps, BigQuery, etc.) launched December 2025.

Using MCP SuperAssistant Extension:

1. Install MCP SuperAssistant Chrome extension
2. Configure your ruflo MCP server
3. Use with Google AI Studio, Gemini, and other AI platforms

Native SDK Integration:

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });

// MCP definitions are natively supported in the Gen AI SDK
const mcpConfig = {
  servers: [{
    name: 'ruflo',
    command: 'npx',
    args: ['ruflo@latest', 'mcp', 'start']
  }]
};

Sources: Google AI Studio MCP, Google Cloud MCP Announcement

JetBrains AI Assistant supports MCP for IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains IDEs.

Setup:

1. Open Settings → Tools → AI Assistant → MCP
2. Click Add Server
3. Configure:

{
  "name": "ruflo",
  "command": "npx",
  "args": ["ruflo@latest", "mcp", "start"]
}

Sources: JetBrains AI Assistant MCP

Environment Variables

All configurations support these environment variables:

MCP Tool Groups

Control which MCP tools are loaded to reduce latency and token usage:

# Enable specific tool groups
export CLAUDE_FLOW_TOOL_GROUPS=implement,test,fix,memory

# Or use a preset mode
export CLAUDE_FLOW_TOOL_MODE=develop

Available Groups: create, issue, branch, implement, test, fix, optimize, monitor, security, memory, all, minimal

Preset Modes:

Precedence: CLI args (--tools=X) > Environment vars > Config file > Default (all)

Security Best Practices

⚠️ Never hardcode API keys in config files checked into version control.

# Use environment variables instead
export ANTHROPIC_API_KEY="sk-ant-..."

# Or use a .env file (add to .gitignore)
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env

Overview

@claude-flow/guidance turns CLAUDE.md into a runtime governance system with enforcement gates, cryptographic proofs, and feedback loops. Agents that normally drift after 30 minutes can now operate for days — rules are enforced mechanically at every step, not remembered by the model.

7-phase pipeline: Compile → Retrieve → Enforce → Trust → Prove → Defend → Evolve

Install

npm install @claude-flow/guidance@alpha

Quick Usage

import {
  createCompiler,
  createRetriever,
  createGates,
  createLedger,
  createProofChain,
} from '@claude-flow/guidance';

// Compile CLAUDE.md into a policy bundle
const compiler = createCompiler();
const bundle = await compiler.compile(claudeMdText);

// Retrieve task-relevant rules
const retriever = createRetriever();
await retriever.loadBundle(bundle);
const { shards, policyText } = await retriever.retrieve({
  taskDescription: 'Fix authentication bug in login flow',
});

// Enforce gates on tool calls
const gates = createGates(bundle);
const result = gates.evaluate({ tool: 'bash', args: { command: 'rm -rf /' } });
// result.blocked === true

// Audit with proof chain
const chain = createProofChain({ signingKey: process.env.PROOF_KEY! });
const envelope = chain.seal(runEvent);
chain.verify(envelope); // true — tamper-evident

Key Modules

Stats

• 1,331 tests across 26 test files
• 27 subpath exports for tree-shaking
• WASM kernel for security-critical hot paths (gates, proof, scoring)
• 25 ADRs documenting every architectural decision

Documentation

• Architecture Overview
• Getting Started
• Enforcement Gates Tutorial
• Proof Audit Trail
• Multi-Agent Security
• API Quick Reference
• Full README

📦 Core Features

Comprehensive capabilities for enterprise-grade AI agent orchestration.

Comprehensive feature set for enterprise-grade AI agent orchestration.

Pre-built agents for every development task, from coding to security audits.

Choose the right topology for your task complexity and team size.

The Hive Mind system implements queen-led hierarchical coordination where strategic queen agents direct specialized workers through collective decision-making and shared memory.

Queen Types:

Worker Specializations (8 types): researcher, coder, analyst, tester, architect, reviewer, optimizer, documenter

Consensus Mechanisms:

Collective Memory Types:

• knowledge (permanent), context (1h TTL), task (30min TTL), result (permanent)
• error (24h TTL), metric (1h TTL), consensus (permanent), system (permanent)

CLI Commands:

npx ruflo hive-mind init                    # Initialize hive mind
npx ruflo hive-mind spawn "Build API"       # Spawn with objective
npx ruflo hive-mind spawn "..." --queen-type strategic --consensus byzantine
npx ruflo hive-mind status                  # Check status
npx ruflo hive-mind metrics                 # Performance metrics
npx ruflo hive-mind memory                  # Collective memory stats
npx ruflo hive-mind sessions                # List active sessions

Performance: Fast batch spawning with parallel agent coordination

Native integration with Claude Code's experimental Agent Teams feature for spawning and coordinating multiple Claude instances.

Enable Agent Teams:

# Automatically enabled with ruflo init
npx ruflo@latest init

# Or manually add to .claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Agent Teams Components:

Quick Start:

// Create a team
TeamCreate({ team_name: "feature-dev", description: "Building feature" })

// Create shared tasks
TaskCreate({ subject: "Design API", description: "..." })
TaskCreate({ subject: "Implement endpoints", description: "..." })

// Spawn teammates (parallel background work)
Task({ prompt: "Work on task #1...", subagent_type: "architect",
       team_name: "feature-dev", name: "architect", run_in_background: true })
Task({ prompt: "Work on task #2...", subagent_type: "coder",
       team_name: "feature-dev", name: "developer", run_in_background: true })

// Message teammates
SendMessage({ type: "message", recipient: "developer",
              content: "Prioritize auth", summary: "Priority update" })

// Cleanup when done
SendMessage({ type: "shutdown_request", recipient: "developer" })
TeamDelete()

Agent Teams Hooks:

# Handle idle teammate
npx ruflo@latest hooks teammate-idle --auto-assign true

# Handle task completion
npx ruflo@latest hooks task-completed --task-id <id> --train-patterns

Display Modes: auto (default), in-process, tmux (split-pane)

Full MCP server with tools for coordination, monitoring, memory, and GitHub integration.

Enterprise-grade security with input validation, sandboxing, and active CVE monitoring.

Production-ready features for high availability and continuous learning.

Build custom plugins with the fluent builder API. Create MCP tools, hooks, workers, and providers.

Plugin Performance: Load <20ms, Hook execution <0.5ms, Worker spawn <50ms

📦 Available Optional Plugins

Install these optional plugins to extend Ruflo capabilities:

🏥 Domain-Specific Plugins

💻 Development Intelligence Plugins

🧠 Advanced AI/Reasoning Plugins

Agentic-QE Plugin Features:

• 58 specialized QE agents across 13 bounded contexts
• 16 MCP tools: aqe/generate-tests, aqe/tdd-cycle, aqe/analyze-coverage, aqe/security-scan, aqe/chaos-inject, etc.
• London-style TDD with red-green-refactor cycles
• O(log n) coverage gap detection with Johnson-Lindenstrauss
• OWASP/SANS compliance auditing

Prime-Radiant Plugin Features:

• 6 mathematical engines for AI interpretability
• 6 MCP tools: pr_coherence_check, pr_spectral_analyze, pr_causal_infer, pr_consensus_verify, pr_quantum_topology, pr_memory_gate
• Sheaf Laplacian coherence detection (<5ms)
• Do-calculus causal inference
• Hallucination prevention via consensus verification

Teammate Plugin Features:

• Native TeammateTool integration for Claude Code v2.1.19+
• 21 MCP tools: teammate/spawn, teammate/coordinate, teammate/broadcast, teammate/discover-teams, teammate/route-task, etc.
• BMSSP WASM acceleration for topology optimization (instant (regex-based, no LLM call))
• Rate limiting with sliding window (configurable limits)
• Circuit breaker for fault tolerance (closed/open/half-open states)
• Semantic routing with skill-based teammate selection
• Health monitoring with configurable thresholds

New RuVector WASM Plugins (50 MCP tools total):

• Healthcare: 5 tools for clinical decision support, drug interactions, treatment recommendations
• Financial: 5 tools for risk assessment, fraud detection, portfolio optimization
• Legal: 5 tools for contract analysis, clause extraction, compliance verification
• Code Intelligence: 5 tools for code analysis, security scanning, architecture mapping
• Test Intelligence: 5 tools for test generation, coverage optimization, mutation testing
• Performance: 5 tools for profiling, bottleneck detection, optimization suggestions
• Neural Coordination: 5 tools for multi-agent learning, knowledge transfer, consensus
• Cognitive Kernel: 5 tools for working memory, attention control, meta-cognition
• Quantum Optimizer: 5 tools for QAOA, VQE, quantum annealing, Grover search
• Hyperbolic Reasoning: 5 tools for Poincaré embeddings, tree inference, taxonomic analysis

# Install Quality Engineering plugin
npm install @claude-flow/plugin-agentic-qe

# Install AI Interpretability plugin
npm install @claude-flow/plugin-prime-radiant

# Install Gas Town Bridge plugin (WASM-accelerated orchestration)
npx ruflo@latest plugins install -n @claude-flow/plugin-gastown-bridge

# Install domain-specific plugins
npm install @claude-flow/plugin-healthcare-clinical
npm install @claude-flow/plugin-financial-risk
npm install @claude-flow/plugin-legal-contracts

# Install development intelligence plugins
npm install @claude-flow/plugin-code-intelligence
npm install @claude-flow/plugin-test-intelligence
npm install @claude-flow/plugin-perf-optimizer

# Install advanced AI/reasoning plugins
npm install @claude-flow/plugin-neural-coordination
npm install @claude-flow/plugin-cognitive-kernel
npm install @claude-flow/plugin-quantum-optimizer
npm install @claude-flow/plugin-hyperbolic-reasoning

# List all installed plugins
npx ruflo plugins list --installed

Intercept and extend any operation with pre/post hooks.

Pre-built WASM plugins for semantic search, intent routing, and pattern storage.

Full PostgreSQL integration with advanced vector operations, attention mechanisms, GNN layers, and self-learning optimization.

MCP Tools (8 tools):

Configuration:

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

const bridge = createRuVectorBridge({
  host: 'localhost',
  port: 5432,
  database: 'vectors',
  user: 'postgres',
  password: 'secret',
  pool: { min: 2, max: 10 },
  ssl: true
});

// Enable the plugin
await registry.register(bridge);
await registry.loadAll();

Attention Mechanisms (39 types):

GNN Layers (15 types):

Hyperbolic Operations:

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

const space = createHyperbolicSpace('poincare', { curvature: -1.0 });

// Embed hierarchical data (trees, taxonomies)
const embedding = await space.embed(vector);
const distance = await space.distance(v1, v2);  // Geodesic distance
const midpoint = await space.geodesicMidpoint(v1, v2);

Self-Learning System:

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

const learning = createSelfLearningSystem(bridge);

// Automatic optimization
await learning.startLearningLoop();  // Runs in background

// Manual optimization
const suggestions = await learning.queryOptimizer.analyze(query);
await learning.indexTuner.tune('my_index');

Hooks (auto-triggered):

Workers run automatically based on context, or dispatch manually via MCP tools.

npx ruflo@latest worker dispatch --trigger audit --context "./src"
npx ruflo@latest worker status

Release Channels

Integration Runtimes

V3 Benchmark Targets

# Initialize ONNX embeddings with hyperbolic config
ruflo embeddings init

# Use larger model for higher quality
ruflo embeddings init --model all-mpnet-base-v2

# Semantic search
ruflo embeddings search -q "authentication patterns"

# Initialize RuVector in PostgreSQL
ruflo ruvector init --database mydb --user admin

# Check connection and schema status
ruflo ruvector status --verbose

# Run pending migrations
ruflo ruvector migrate --up

# Performance benchmark
ruflo ruvector benchmark --iterations 1000

# Optimize indices and vacuum
ruflo ruvector optimize --analyze

# Backup vector data
ruflo ruvector backup --output ./backup.sql

| Feature | Description | Capability | |---------|-------------|