Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ruvnet/ruflo/llms.txt

Use this file to discover all available pages before exploring further.

A swarm is a group of specialised agents that collaborate on a single objective. Instead of one agent attempting a complex task end-to-end — and drifting from the original goal as context grows — the swarm decomposes work across typed agents, coordinates their outputs through a chosen topology, and reaches agreement via a consensus algorithm. The result is implementations that stay aligned with their specifications even when dozens of agents are working in parallel. Ruflo’s swarm coordinator is built on the UnifiedSwarmCoordinator (ADR-003), the single canonical engine that consolidates four legacy coordination systems into one.

​
Topologies

The topology determines how agents communicate with each other:
TopologyPatternBest For
hierarchicalA queen coordinator validates each worker’s output before it can proceed. Single chain of authority.Complex coding tasks, spec compliance, anti-drift — recommended default
meshEvery agent is connected to every other. Fully peer-to-peer.Distributed parallel work where agents need to share intermediate results
ringAgents pass tasks sequentially around a ring. Each agent consumes the previous agent’s output.Pipeline workflows (e.g. generate → test → review → document)
starA central hub dispatches tasks to spoke agents and collects results. Simple fan-out.Simple parallelisable tasks with no inter-agent dependencies
Hierarchical is the recommended topology for software development tasks. The coordinator validates each output against the original goal and catches divergence early — before it compounds across agents.

​
Consensus Algorithms

Consensus determines how agents agree on decisions, especially when some agents fail or return conflicting results:
AlgorithmHow It WorksFault ToleranceBest For
raftA leader-elected node maintains authoritative state; all writes go through the leaderTolerates up to half of agents failingStrongly consistent state — no conflicting decisions; recommended for coding tasks
byzantine (BFT)Practical Byzantine Fault Tolerance; requires a ⅔ supermajority to commit any decisionTolerates up to ⅓ faulty or malicious agentsAdversarial environments; critical decision points where some agents may behave incorrectly
gossipEpidemic dissemination; state propagates peer-to-peer until eventually consistentHigh partition toleranceLarge agent networks where eventual consistency is acceptable and throughput matters more than immediacy

​
Hive-Mind (Most Common Usage)

For most tasks, hive-mind spawn is the right entry point. It initialises a queen-led hierarchical swarm, decomposes the objective into sub-tasks, assigns them to appropriate worker types, and manages the full lifecycle: 
# Start a hive-mind swarm with a plain-English objective
npx ruflo@latest hive-mind spawn "Implement user authentication"

# Customise topology and agent count
npx ruflo@latest hive-mind spawn "Build REST API" --topology mesh --max-agents 8

# Use a strategic queen for high-level planning tasks
npx ruflo@latest hive-mind spawn "Design microservices architecture" \
  --queen-type strategic --consensus byzantine

# Check status of a running hive-mind
npx ruflo@latest hive-mind status

# View collective memory and task metrics
npx ruflo@latest hive-mind metrics

​
Manual Swarm Control

When you need direct control over swarm lifecycle: 
# Initialise a swarm with explicit topology and agent count
npx ruflo@latest swarm init --topology hierarchical --max-agents 6

# Check which agents are active and what they're doing
npx ruflo@latest swarm status

# Stop the swarm cleanly (agents flush memory before exit)
npx ruflo@latest swarm stop

​
Anti-Drift Configuration

Complex swarms can drift from their original goals as context accumulates. The following defaults keep agents on-task:
SettingRecommended ValueWhy It Prevents Drift
topologyhierarchicalCoordinator validates each output against the goal, catching divergence early
maxAgents6–8Fewer agents = less coordination overhead and easier alignment
strategyspecializedClear role boundaries — each agent knows exactly what to do, no overlap
consensusraftLeader maintains authoritative state; no conflicting decisions
Additional anti-drift mechanisms enabled automatically:
  • Frequent checkpoints via post-task hooks
  • Shared memory namespace visible to all agents in the swarm
  • Short task cycles with verification gates
  • Hierarchical coordinator reviews all agent outputs before they are committed
Task → Agent routing recommendations:
Task TypeRecommended Agents
Bug fixcoordinator, researcher, coder, tester
New featurecoordinator, architect, coder, tester, reviewer
Refactorcoordinator, architect, coder, reviewer
Performancecoordinator, perf-analyzer, coder
Securitycoordinator, security-architect, security

​
TypeScript API

The @claude-flow/swarm package (ADR-003) exports a single canonical coordinator. Use createUnifiedSwarmCoordinator — the factory function that handles sensible defaults: 
import { createUnifiedSwarmCoordinator } from '@claude-flow/swarm';

const coordinator = createUnifiedSwarmCoordinator({
  topology: { type: 'hierarchical', maxAgents: 15 },
  consensus: { algorithm: 'raft', threshold: 0.66 },
});

await coordinator.initialize();
The default configuration (used when no options are passed) is: 
// DEFAULT_CONFIG from @claude-flow/swarm
{
  topology: {
    type: 'hierarchical',
    maxAgents: 15,
  },
  consensus: {
    algorithm: 'raft',
    threshold: 0.66,
    timeoutMs: 5000,
  },
  messageBus: {
    maxQueueSize: 10000,
    batchSize: 100,
  },
  agentPool: {
    minAgents: 1,
    maxAgents: 15,
    idleTimeoutMs: 300000,
  },
}
The package also exports QueenCoordinator, TopologyManager, MessageBus, AgentPool, RaftConsensus, ByzantineConsensus, and GossipConsensus for lower-level composition. See the @claude-flow/swarm source for the full type surface.

​
MCP Tools

When Ruflo is registered as an MCP server, these swarm tools are callable from Claude Code:
ToolDescription
swarm_initInitialise a swarm with a given topology, max agents, and consensus algorithm
swarm_statusReturn the current status of all active swarms, agent counts, and task queues
Use swarm_init with topology=hierarchical, maxAgents=6, 
then assign the authentication refactor task to the swarm.
MCP tools (swarm_init, swarm_status, etc.) are only available after running npx ruflo init and registering the MCP server with claude mcp add ruflo -- npx ruflo@latest mcp start. The Claude Code Plugin (lite) path does not register the MCP server.

Build docs developers (and LLMs) love

Get started for freeTalk to us