Claude Code Configuration - Ruflo v3.5

Ruflo v3.6 (2026-04-29) — Stable release with agent federation and comms-first coordination. 6,000+ commits, 314 MCP tools, 16 agent roles + custom types, 19 AgentDB controllers, 21 native plugins. Packages: @claude-flow/cli@3.6.10, claude-flow@3.6.10, ruflo@3.6.10

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

Package	Path	Purpose
`@claude-flow/cli`	`v3/@claude-flow/cli/`	CLI entry point (26 commands)
`@claude-flow/codex`	`v3/@claude-flow/codex/`	Dual-mode Claude + Codex collaboration
`@claude-flow/guidance`	`v3/@claude-flow/guidance/`	Governance control plane
`@claude-flow/hooks`	`v3/@claude-flow/hooks/`	17 hooks + 12 workers
`@claude-flow/memory`	`v3/@claude-flow/memory/`	AgentDB + HNSW search
`@claude-flow/security`	`v3/@claude-flow/security/`	Input validation, CVE remediation

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, ADR-143)

Tier	Handler	Latency	Cost	Use Cases
1	Deterministic codemod	~1ms	$0	Structural transforms with no LLM: `var-to-const`, `remove-console`, `add-logging`
2	Haiku	~500ms	$0.0002	Simple tasks, low complexity (<30%)
3	Sonnet/Opus	2-5s	$0.003-0.015	Complex reasoning, architecture, security (>30%)

Always check for [CODEMOD_AVAILABLE] or [TASK_MODEL_RECOMMENDATION] before spawning agents
When you see [CODEMOD_AVAILABLE], call the hooks_codemod MCP tool (intent + file) — it applies the transform deterministically via the TypeScript compiler at $0, no LLM. Deterministic intents only: var-to-const, remove-console, add-logging
add-types, add-error-handling, async-await need judgement and route to a model (Tier 2/3) — they are not $0 codemods (see ADR-143)
Agent Booster (agent-booster) is a fast-apply merge engine for arbitrary LLM-produced edit snippets, not an intent-transform engine — it is not the Tier-1 path

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?

Single Platform	Dual-Mode Collaboration
One model's perspective	Two AI platforms cross-validating
Limited reasoning styles	Complementary strengths
No external verification	Built-in code review
Sequential workflows	Parallel execution

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)

Template	Workers	Pipeline
`feature`	🔵 Architect → 🟢 Coder → 🔵 Tester → 🟢 Reviewer	Full feature development
`security`	🔵 Analyst → 🟢 Scanner → 🔵 Reporter	Security audit workflow
`refactor`	🔵 Architect → 🟢 Refactorer → 🔵 Tester	Code modernization
`bugfix`	🔵 Researcher → 🟢 Coder → 🔵 Tester	Bug investigation & fix

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

Task Type	Preferred Platform	Reason
Architecture & Design	🔵 Claude	Strong reasoning, system thinking
Implementation	🟢 Codex	Fast code generation
Security Review	🔵 Claude	Careful analysis, threat modeling
Performance Optimization	🟢 Codex	Code-level optimizations
Testing Strategy	🔵 Claude	Coverage analysis, edge cases
Refactoring	🟢 Codex	Bulk code transformations

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
mcp__ruv-swarm__swarm_init({
  topology: "hierarchical",
  maxAgents: 8,
  strategy: "specialized"
})

// STEP 2: Spawn NAMED agents concurrently — all in ONE message
// Each agent knows WHO to message next in the pipeline
Task({
  prompt: "Research requirements and codebase. SendMessage findings to 'architect' when done.",
  subagent_type: "researcher", name: "researcher", run_in_background: true
})
Task({
  prompt: "Wait for research from 'researcher'. Design implementation. SendMessage design to 'coder'.",
  subagent_type: "system-architect", name: "architect", run_in_background: true
})
Task({
  prompt: "Wait for design from 'architect'. Implement the solution. SendMessage code paths to 'tester'.",
  subagent_type: "coder", name: "coder", run_in_background: true
})
Task({
  prompt: "Wait for implementation from 'coder'. Write tests. SendMessage results to 'reviewer'.",
  subagent_type: "tester", name: "tester", run_in_background: true
})
Task({
  prompt: "Wait for test results from 'tester'. Review code quality and security. Report findings.",
  subagent_type: "reviewer", name: "reviewer", run_in_background: true
})

// STEP 3: Kick off the pipeline
SendMessage({ to: "researcher", summary: "Start research", message: "[task description and context]" })

// STEP 4: Batch todos
TodoWrite({ todos: [
  {content: "Research and analyze requirements", status: "in_progress", activeForm: "Researching"},
  {content: "Design architecture", status: "pending", activeForm: "Designing"},
  {content: "Implement solution", status: "pending", activeForm: "Implementing"},
  {content: "Write tests", status: "pending", activeForm: "Testing"},
  {content: "Review and finalize", status: "pending", activeForm: "Reviewing"}
]})

// Pipeline flow via SendMessage:
// researcher ──→ architect ──→ coder ──→ tester ──→ reviewer

Agent Routing (Anti-Drift)

Code	Task	Agents
1	Bug Fix	coordinator, researcher, coder, tester
3	Feature	coordinator, architect, coder, tester, reviewer
5	Refactor	coordinator, architect, coder, reviewer
7	Performance	coordinator, perf-engineer, coder
9	Security	coordinator, security-architect, auditor
11	Memory	coordinator, memory-specialist, perf-engineer
13	Docs	researcher, api-docs

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 (measured ~1.9x at N=20k, ~3.2x–4.7x at N=5k vs brute force; ANN wins above the crossover)
Neural Learning: Enabled (SONA)

V3 CLI Commands (26 Commands, 140+ Subcommands)

Core Commands

Command	Subcommands	Description
`init`	4	Project initialization with wizard, presets, skills, hooks
`agent`	8	Agent lifecycle (spawn, list, status, stop, metrics, pool, health, logs)
`swarm`	6	Multi-agent swarm coordination and orchestration
`memory`	11	AgentDB memory with HNSW vector search (measured ~1.9x–4.7x vs brute force above crossover)
`mcp`	9	MCP server management and tool execution
`task`	6	Task creation, assignment, and lifecycle
`session`	7	Session state management and persistence
`config`	7	Configuration management and provider setup
`status`	3	System status monitoring with watch mode
`start`	3	Service startup and quick launch
`workflow`	6	Workflow execution and template management
`hooks`	17	Self-learning hooks + 12 background workers
`hive-mind`	6	Queen-led Byzantine fault-tolerant consensus

Advanced Commands

Command	Subcommands	Description
`daemon`	5	Background worker daemon (start, stop, status, trigger, enable)
`neural`	5	Neural pattern training (train, status, patterns, predict, optimize)
`security`	6	Security scanning (scan, audit, cve, threats, validate, report)
`performance`	5	Performance profiling (benchmark, profile, metrics, optimize, report)
`providers`	5	AI providers (list, add, remove, test, configure)
`plugins`	5	Plugin management (list, install, uninstall, enable, disable)
`deployment`	5	Deployment management (deploy, rollback, status, environments, release)
`embeddings`	4	Vector embeddings (embed, batch, search, init) — agentic-flow ONNX backend (speedup unverified, no benchmark)
`claims`	4	Claims-based authorization (check, grant, revoke, list)
`migrate`	5	V2 to V3 migration with rollback support
`process`	4	Background process management
`doctor`	1	System diagnostics with health checks
`completions`	4	Shell completions (bash, zsh, fish, powershell)

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

Flag	Purpose
`-p, --print`	Non-interactive mode, print and exit
`--model <model>`	Select model (haiku, sonnet, opus)
`--output-format <fmt>`	Output: text, json, stream-json
`--max-budget-usd <amt>`	Spending cap per invocation
`--allowedTools <tools>`	Restrict available tools
`--append-system-prompt`	Add custom instructions
`--resume <id>`	Continue a previous session
`--fork-session`	Branch from resumed session
`--fallback-model <model>`	Auto-fallback if primary overloaded
`--permission-mode <mode>`	acceptEdits, bypassPermissions, plan, etc.
`--mcp-config <json>`	Load MCP servers from JSON

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);

Feature	Token Savings
ReasoningBank retrieval	-32%
Agent Booster edits	-15%
Cache (95% hit rate)	-10%
Optimal batch size	-20%

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 & Comms System

Agent Teams turns Claude Code into a multi-agent system where named agents communicate in real-time via SendMessage. The comms system is the primary coordination mechanism — agents talk to each other, not just to the lead.

Architecture

Team Lead (you)
  ├── SendMessage ←→ architect (named agent)
  ├── SendMessage ←→ developer (named agent)
  ├── SendMessage ←→ tester (named agent)
  └── SendMessage ←→ reviewer (named agent)
       ↕ agents can message each other by name

Core Principle: Named Agents + SendMessage

Every agent MUST have a name so it's addressable. Communication happens via SendMessage, not polling or shared memory.

// STEP 1: Spawn named agents (all in ONE message, background)
Task({
  prompt: "Design the API. When done, send your design to 'developer' via SendMessage.",
  subagent_type: "system-architect",
  name: "architect",
  run_in_background: true
})
Task({
  prompt: "Wait for architect's design via SendMessage. Then implement it. Send code to 'tester'.",
  subagent_type: "coder",
  name: "developer",
  run_in_background: true
})
Task({
  prompt: "Wait for developer's code via SendMessage. Write tests. Send results to 'reviewer'.",
  subagent_type: "tester",
  name: "tester",
  run_in_background: true
})

// STEP 2: Kick off the pipeline by messaging the first agent
SendMessage({
  to: "architect",
  summary: "Start API design",
  message: "Design a REST API for user management with CRUD endpoints. Send the design to 'developer' when done."
})

SendMessage Protocol

// Lead → Teammate: assign work
SendMessage({ to: "developer", summary: "Implement auth", message: "Build OAuth2 flow..." })

// Lead → Teammate: redirect priorities
SendMessage({ to: "developer", summary: "Prioritize auth", message: "Auth endpoint is blocking tester, do it first." })

// Lead → Teammate: provide context from another agent's results
SendMessage({ to: "tester", summary: "Architect output", message: "The architect designed these endpoints: [details]. Write tests for them." })

// Lead → Teammate: graceful shutdown
SendMessage({ to: "developer", message: { type: "shutdown_request" } })

Coordination Patterns

Pipeline (A → B → C) — each agent messages the next when done:

architect ──SendMessage──→ developer ──SendMessage──→ tester ──SendMessage──→ reviewer

Tell each agent WHO to message next in their prompt.

Fan-out / Fan-in — lead spawns parallel agents, collects results:

         ┌→ researcher-1 ──→┐
lead ────┼→ researcher-2 ──→├──→ lead synthesizes
         └→ researcher-3 ──→┘

Spawn with run_in_background: true. Results arrive as task completions.

Supervisor / Worker — lead assigns, workers report back:

lead ←──SendMessage──→ worker-1
lead ←──SendMessage──→ worker-2
lead ←──SendMessage──→ worker-3

Lead sends tasks via SendMessage, workers respond with results.

Agent Prompt Template (Comms-Aware)

When spawning agents that need to coordinate, include comms instructions:

Task({
  prompt: `You are the architect for this feature team.

YOUR TASK: Design the database schema for user management.

COMMS PROTOCOL:
- When your design is ready, send it to "developer" via SendMessage
- If you need clarification, message the team lead (just output text)
- Include file paths and key decisions in your message

DELIVERABLE: Schema design with entity relationships, indexes, and migration plan.`,
  subagent_type: "system-architect",
  name: "architect",
  run_in_background: true
})

Full Team Spawn Example

// Create shared task list first
TaskCreate({ subject: "Design schema", description: "...", activeForm: "Designing" })
TaskCreate({ subject: "Implement models", description: "...", activeForm: "Implementing" })
TaskCreate({ subject: "Write tests", description: "...", activeForm: "Testing" })
TaskCreate({ subject: "Security review", description: "...", activeForm: "Reviewing" })

// Spawn ALL named agents in ONE message
Task({
  prompt: "Design the schema. SendMessage to 'developer' with your design when done. Update task #1.",
  subagent_type: "system-architect", name: "architect", run_in_background: true
})
Task({
  prompt: "Wait for schema from 'architect'. Implement models + endpoints. SendMessage to 'tester'. Update task #2.",
  subagent_type: "coder", name: "developer", run_in_background: true
})
Task({
  prompt: "Wait for code from 'developer'. Write integration tests. SendMessage results to 'security'. Update task #3.",
  subagent_type: "tester", name: "tester", run_in_background: true
})
Task({
  prompt: "Wait for test results from 'tester'. Review for vulnerabilities. Update task #4.",
  subagent_type: "security-auditor", name: "security", run_in_background: true
})

Agent Teams Hooks

Hook	Trigger	Purpose
`TeammateIdle`	Teammate finishes turn	Auto-assign pending tasks via SendMessage
`TaskCompleted`	Task marked complete	Train patterns, notify lead via SendMessage

npx claude-flow@v3alpha hooks teammate-idle --auto-assign true
npx claude-flow@v3alpha hooks task-completed -i task-123 --train-patterns true

Rules

Always name agents — use name: "role-name" so they're addressable
Comms over memory — use SendMessage for real-time coordination, memory for persistence
Pipeline prompts — tell each agent WHO to message next and WHAT to send
Spawn all at once — all Task calls in ONE message with run_in_background: true
Don't poll — agents message back when done; wait for task completion notifications
Graceful shutdown — send { type: "shutdown_request" } before TeamDelete
Lead synthesizes — when agents complete, review ALL results before responding to user

V3 Hooks System (17 Hooks + 12 Workers)

Hook Categories

Category	Hooks	Purpose
Core	`pre-edit`, `post-edit`, `pre-command`, `post-command`, `pre-task`, `post-task`	Tool lifecycle
Session	`session-start`, `session-end`, `session-restore`, `notify`	Context management
Intelligence	`route`, `explain`, `pretrain`, `build-agents`, `transfer`	Neural learning
Learning	`intelligence` (trajectory-start/step/end, pattern-store/search, stats, attention)	Reinforcement
Agent Teams	`teammate-idle`, `task-completed`	Multi-agent coordination

12 Background Workers

Worker	Priority	Description
`ultralearn`	normal	Deep knowledge acquisition
`optimize`	high	Performance optimization
`consolidate`	low	Memory consolidation
`predict`	normal	Predictive preloading
`audit`	critical	Security analysis
`map`	normal	Codebase mapping
`preload`	low	Resource preloading
`deepdive`	normal	Deep code analysis
`document`	normal	Auto-documentation
`refactor`	normal	Refactoring suggestions
`benchmark`	normal	Performance benchmarking
`testgaps`	normal	Test coverage analysis

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 (measured numbers: see audit + scripts/benchmark-intelligence.mjs):

SONA: Self-Optimizing Neural Architecture (measured 0.0043ms/adapt, target <0.05ms met)
MoE: Mixture of Experts for specialized routing (gate converges — confidence 0.13→0.88 after rewards)
HNSW: measured ~1.9x at N=20k, ~3.2x–4.7x at N=5k vs brute force (recall@10 ~0.99); ANN wins above the crossover, ruvector NAPI backend (WASM not active on test host)
EWC++: Elastic Weight Consolidation (prevents forgetting)
Flash Attention: unverified — no benchmark exists for this claim

The 4-step intelligence pipeline:

RETRIEVE — Fetch relevant patterns via HNSW
JUDGE — Evaluate with verdicts (success/failure)
DISTILL — Extract key learnings via LoRA
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
agentic-flow ONNX integration: speedup unverified (no benchmark; backend reported onnx, model all-MiniLM-L6-v2, 384-dim)
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

Source of truth: docs/reviews/intelligence-system-audit-2026-05-29.md + scripts/benchmark-intelligence.mjs. Numbers below are measured unless marked "target/unverified".

Metric	Measured / Target	Status
HNSW Search	~1.9x at N=20k, ~3.2x–4.7x at N=5k vs brute force (recall@10 ~0.99); ties/loses below crossover	Measured (ruvector NAPI; 150x-12,500x NOT reproduced — was brute-force fallback)
Int8 Quantization	3.84x compression, reconstruction cosine 0.99999	Measured
RaBitQ Quantization	32x compression, 0.60ms/query (14,760-vec index)	Measured
SONA Adaptation	0.0043ms/adapt (target <0.05ms met)	Measured
MoE Gate	converges — confidence 0.13→0.88, Q 0→99.8 after rewards	Measured
Flash Attention	2.49x-7.47x	Unverified (no benchmark exists)
MCP Response	<100ms	target
CLI Startup	<500ms	target

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

Tool	Description
`memory_import_claude`	Import Claude Code memories into AgentDB with 384-dim ONNX embeddings. Use `allProjects: true` to import from ALL projects.
`memory_bridge_status`	Show bridge health — Claude files, AgentDB entries, SONA state, connection status
`memory_search_unified`	Semantic search across ALL namespaces (claude-memories, auto-memory, patterns, tasks, feedback)

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

Component	Status	Details
ONNX Embeddings	Active	all-MiniLM-L6-v2, 384 dimensions
SONA Learning	Active	Pattern matching + trajectory recording
ReasoningBank	Active	Pattern storage with file persistence
AgentDB sql.js	Active	SQLite with vector_indexes table

Publishing to npm

Versioning policy (stable releases — alpha series ended at 3.7.0-alpha.81, 2026-05-23)

From 3.7.0 onward we ship stable semver, NOT alpha pre-releases.
Bump rules (semver discipline):
- PATCH (3.7.0 → 3.7.1): bug fixes only, no API change, no schema change
- MINOR (3.7.0 → 3.8.0): backward-compatible additions (new MCP tool, new flag, new agent type)
- MAJOR (3.x → 4.0.0): breaking change in CLI surface, MCP tool signature, file layout, or default behavior
Default tag is latest (no --tag alpha). The alpha and v3alpha dist-tags continue to exist for historical compatibility — point them at the same version as latest.
Never publish a pre-release (-alpha.N, -beta.N, -rc.N) unless the user explicitly asks for a pre-release flow.

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 (latest + alpha + v3alpha all point to the same version)
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

# Replace 3.7.1 below with your chosen stable version (patch/minor/major per the rules above)

# STEP 1: Build and publish @claude-flow/cli
cd v3/@claude-flow/cli
npm version 3.7.1 --no-git-tag-version
npm run build
npm publish                              # default tag is `latest` — no --tag flag
npm dist-tag add @claude-flow/cli@3.7.1 alpha     # historical compat
npm dist-tag add @claude-flow/cli@3.7.1 v3alpha   # historical compat

# STEP 2: Publish claude-flow umbrella
cd /Users/cohen/Projects/ruflo                    # or your repo root
npm version 3.7.1 --no-git-tag-version
npm publish
npm dist-tag add claude-flow@3.7.1 alpha
npm dist-tag add claude-flow@3.7.1 v3alpha

# STEP 3: Publish ruflo wrapper (CRITICAL — DON'T FORGET — this is what users run)
cd ruflo
npm version 3.7.1 --no-git-tag-version
npm publish
npm dist-tag add ruflo@3.7.1 alpha
npm dist-tag add ruflo@3.7.1 v3alpha

Verification (run before telling user publishing is complete):

for pkg in @claude-flow/cli claude-flow ruflo; do
  echo "$pkg: $(npm view $pkg@latest version)"
  npm view $pkg dist-tags --json
done
# All three must show latest === alpha === v3alpha === new version

All Tags That Must Be Updated

Package	Tag	Command Users Run
`@claude-flow/cli`	`latest`	`npx @claude-flow/cli@latest`
`@claude-flow/cli`	`alpha`	`npx @claude-flow/cli@alpha` (legacy compat)
`@claude-flow/cli`	`v3alpha`	`npx @claude-flow/cli@v3alpha` (legacy compat)
`claude-flow`	`latest`	`npx claude-flow@latest`
`claude-flow`	`alpha`	`npx claude-flow@alpha` (legacy compat)
`claude-flow`	`v3alpha`	`npx claude-flow@v3alpha` (legacy compat)
`ruflo`	`latest`	`npx ruflo@latest`
`ruflo`	`alpha`	`npx ruflo@alpha` (legacy compat)
`ruflo`	`v3alpha`	`npx ruflo@v3alpha` (legacy compat)

Never forget the ruflo package — it's the thin wrapper users actually run via npx ruflo
The legacy alpha and v3alpha tags MUST stay pointed at the latest stable so old install commands keep working
ruflo source is in /ruflo/ — it depends on @claude-flow/cli
Also remember to update ruflo/package.json overrides when adding new pinned transitives (see #2112 lesson — root overrides do NOT propagate to the published ruflo wrapper)

GitHub Release after publish

Every stable bump SHOULD have a matching gh release create v<version> with consolidated release notes pointing at the gist if one exists. Example:

git tag v3.7.1 main
git push origin v3.7.1
gh release create v3.7.1 --title "v3.7.1 — <one-line headline>" \
  --notes-file /tmp/release-notes.md

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

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

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"
}

Update counts and arrays:
- Increment totalPlugins
- Add to official array
- Add to featured/newest if applicable
- Update category pluginCount
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

Update discovery.ts with new CID:

export const LIVE_REGISTRY_CID = 'NEW_CID_FROM_PINATA';

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'

MetaHarness Integration (ADR-150)

Ruflo integrates with the upstream metaharness / @metaharness/* ecosystem as a sibling agent-harness scaffolding system (same author, designed around ruflo's primitives). Both metaharness and @metaharness/router are in optionalDependencies — never required at runtime.

Architectural constraint (load-bearing)

Ruflo remains operational if every MetaHarness package is removed. Four rules:

Removable: npm ls --without @metaharness/* must still produce a working CLI
Optional in package.json: @metaharness/* packages MUST be in optionalDependencies, never in dependencies
Graceful degradation: every code path that touches MetaHarness catches MODULE_NOT_FOUND and falls back
CI gate: .github/workflows/no-metaharness-smoke.yml enforces all three by static grep + runtime drill on every PR

Command + tool surface

# CLI subcommands (npx ruflo metaharness …)
npx ruflo metaharness score                      # 5-dim readiness scorecard
npx ruflo metaharness genome                     # 7-section categorical report
npx ruflo metaharness mcp-scan --fail-on high    # static security findings
npx ruflo metaharness threat-model               # enterprise threat report
npx ruflo metaharness oia-audit --alert-on-worst high
                                                 # composite weekly audit → memory
npx ruflo metaharness audit-list --since 30d     # enumerate audit records
npx ruflo metaharness audit-trend \              # diff two audits (drift)
  --baseline-key <a> --current-key <b> --alert-on-worsening \
  --alert-on-distance-below 0.85               # iter 38 — structural-distance gate (ADR-152 §3.1)
npx ruflo metaharness similarity \               # iter 36 — ADR-152 §3.1 weighted similarity
  --a a.json --b b.json [--per-dimension] [--alert-below 0.5]
npx ruflo metaharness drift-from-history \       # iter 53 — 1-command drift (composes 3 primitives)
  [--baseline-since 7d] [--baseline-key <key>] [--baseline-file <path>] \
  [--threshold 0.95] [--alert-on-new-severity high] [--dry-run]
                                                 # iter 66 — --baseline-key skips audit-list (~14x faster)
                                                 # iter 67 — --baseline-file skips memory entirely (~19x faster)
                                                 # iter 78 — --alert-on-new-severity adds orthogonal finding-severity gate
npx ruflo metaharness mint --name foo --template vertical:coding --confirm

# Dedicated command
npx ruflo eject --name my-harness                # lift ruflo project → standalone harness
                                                 # dry-run by default; refuses in-repo target

# Doctor health check
npx ruflo doctor --component metaharness         # report metaharness availability + version

# MCP tools (callable by Claude Code agents)
mcp__claude-flow__metaharness_score
mcp__claude-flow__metaharness_genome
mcp__claude-flow__metaharness_mcp_scan
mcp__claude-flow__metaharness_threat_model
mcp__claude-flow__metaharness_oia_audit
mcp__claude-flow__metaharness_audit_list
mcp__claude-flow__metaharness_audit_trend
mcp__claude-flow__metaharness_similarity          # iter 36 — ADR-152 §3.1 genome similarity
mcp__claude-flow__metaharness_drift_from_history  # iter 53 — 1-command drift detection

Routing integration (ADR-148/149)

@metaharness/router@~0.3.2 is wired as the cost-optimal model router behind the CLAUDE_FLOW_ROUTER_NEURAL=1 triple-gate. The routedBy field on every routing decision carries 'metaharness-knn' | 'metaharness-krr' | 'fastgrnn' when the neural path is active.

SelfEvolvingRouter parallel-logging (ADR-150 Phase 2)

When CLAUDE_FLOW_ROUTER_PARALLEL_LOG=1 is set, every route() call writes a paired-decision row (bandit pick + neural-augmented pick + outcome) to .swarm/router-parallel.jsonl. Analyze with:

node plugins/ruflo-metaharness/scripts/router-parallel-analyze.mjs \
  --input .swarm/router-parallel.jsonl --strict

The 3-criteria AND-gate from ADR-150 review-round-1: quality > 2% AND cost < 1% AND latency < 5%. Exit 1 in --strict mode if any criterion fails — promotion gate.

CI workflows

metaharness-ci.yml — score / mcp-scan / router-compat / eject-dryrun jobs on every PR touching plugins/ruflo-metaharness/**
no-metaharness-smoke.yml — enforces the four architectural-constraint rules above on every PR
oia-audit-weekly.yml — Sundays 04:17 UTC, runs composite audit, uploads 90-day artifact

Cross-references

ADR-150 — decision + implementation notes
Issue #2399 — phase tracker
Research gist — graded evidence
Upstream: github.com/ruvnet/agent-harness-generator

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

Plugin	Version	Description
`@claude-flow/embeddings`	3.0.0-alpha.1	Vector embeddings with sql.js, HNSW, hyperbolic support
`@claude-flow/security`	3.0.0-alpha.1	Input validation, path security, CVE remediation
`@claude-flow/claims`	3.0.0-alpha.8	Claims-based authorization (check, grant, revoke, list)
`@claude-flow/neural`	3.0.0-alpha.7	Neural pattern training (SONA, MoE, EWC++)
`@claude-flow/plugins`	3.0.0-alpha.1	Plugin system core (manager, discovery, store)
`@claude-flow/performance`	3.0.0-alpha.1	Performance profiling and benchmarking

Integration Plugins

Plugin	Version	Description
`@claude-flow/plugin-agentic-qe`	3.0.0-alpha.4	Agentic quality engineering integration
`@claude-flow/plugin-prime-radiant`	0.1.5	Prime Radiant intelligence integration
`@claude-flow/plugin-gastown-bridge`	3.0.0-alpha.1	Gastown bridge protocol integration
`@claude-flow/teammate-plugin`	1.0.0-alpha.1	Multi-agent teammate coordination
`@claude-flow/plugin-code-intelligence`	0.1.0	Advanced code analysis and intelligence
`@claude-flow/plugin-test-intelligence`	0.1.0	Intelligent test generation and gap analysis
`@claude-flow/plugin-perf-optimizer`	0.1.0	Performance optimization automation
`@claude-flow/plugin-neural-coordinator`	0.1.0	Neural network coordination across agents
`@claude-flow/plugin-cognitive-kernel`	0.1.0	Core cognitive processing kernel
`@claude-flow/plugin-quantum-optimizer`	0.1.0	Quantum-inspired optimization algorithms
`@claude-flow/plugin-hyperbolic-reasoning`	0.1.0	Hyperbolic space reasoning for hierarchical data

Domain-Specific Plugins

Plugin	Version	Description
`@claude-flow/plugin-healthcare-clinical`	0.1.0	Healthcare clinical workflow automation
`@claude-flow/plugin-financial-risk`	0.1.0	Financial risk assessment and modeling
`@claude-flow/plugin-legal-contracts`	0.1.0	Legal contract analysis and generation

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!

Uh oh!

FilesExpand file tree

CLAUDE.md

Latest commit

History