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

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

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:

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

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 f