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.

ruflo swarm coordinates groups of agents working toward a shared objective. A swarm wires agents together using a chosen topology (who talks to whom), a coordination strategy (what roles exist), and a consensus algorithm (how decisions are made when agents disagree). Use swarm init to declare the topology, swarm start to assign an objective and deploy agents, and swarm status to track progress in real time.

​
Synopsis

ruflo swarm <subcommand> [options]

​
Subcommands

SubcommandDescription
initCreate a new swarm topology via the MCP layer
startStart swarm execution against an objective
statusShow live progress, agent counts, task breakdown, and coordination stats
stopGracefully (or forcefully) stop a running swarm
scaleAdjust the number of agents in a running swarm
coordinateDeploy the full V3 15-agent hierarchical-mesh topology

​
Swarm topologies

TopologyDescriptionBest for
hierarchicalQueen-led tree; coordinator validates every agent outputComplex tasks where drift prevention matters
hierarchical-meshQueen + peer communication (V3 default, 15-agent)Maximum flexibility with drift control
meshFully connected peer-to-peer; every agent talks to every otherResearch, creative tasks, small teams
ringCircular token-passing patternOrdered pipeline workflows
starCentral coordinator with spokes; no peer-to-peerHub-spoke orchestration
hybridHierarchical mesh — alias for hierarchical-mesh—
The hierarchical topology is the recommended anti-drift configuration. A single coordinator validates each output against the goal and catches divergence early. Pair it with --max-agents 6-8 and --strategy specialized for the best results on coding tasks.

​
Coordination strategies

StrategyAgents deployedUse case
specializedcoordinator, researcher, architect, 2× coder, tester, reviewerDefault for most tasks — clear roles reduce ambiguity
developmentcoordinator, architect, 3× coder, 2× tester, reviewerFull feature development pipeline
researchcoordinator, 4× researcher, 2× analystData gathering and synthesis
testingtest lead, 2× unit tester, 2× integration tester, QA reviewerComprehensive test coverage
optimizationperformance lead, 2× profiler, 2× optimizerPerformance tuning
balancedcoordinator, 4× worker, reviewerEven workload distribution
adaptivecoordinator, scout, 3× workerDynamic, exploratory tasks
maintenancecoordinator, 2× refactorer, documenterCodebase cleanup
analysisanalyst lead, 2× code analyst, security analystAudit and documentation

​
init

Register a new swarm topology and persist the configuration to .swarm/state.json. 
ruflo swarm init [options]
​
--topology / -t
string
default:"hierarchical"
Swarm topology. One of: hierarchical, hierarchical-mesh, mesh, ring, star, hybrid.
​
--max-agents / -m
number
default:"15"
Maximum number of concurrent agents this swarm can host.
​
--strategy / -s
string
Coordination strategy. See the strategies table above for valid values.
​
--auto-scale
boolean
default:"true"
Allow the swarm to grow and shrink within --max-agents based on task demand.
​
--v3-mode
boolean
default:"false"
Enable V3 enhancements: hierarchical-mesh topology, Flash Attention, AgentDB integration, and SONA learning.

​
start

Assign an objective to the swarm, compute an agent deployment plan, call swarm_init via MCP, and persist the execution state to .swarm/state.json. 
ruflo swarm start --objective "<objective>" [options]
​
--objective / -o
string
required
The task or goal the swarm should accomplish.
​
--strategy / -s
string
Execution strategy. Determines which agent types are deployed and in what ratio.
​
--parallel / -p
boolean
default:"true"
Allow agents to run tasks concurrently.
​
--monitor
boolean
default:"true"
Enable real-time monitoring output.
swarm start sets up coordination state and registers agents. Actual code execution happens through Claude Code’s Task tool, headless claude -p workers, or hive-mind spawn --claude. Use swarm status <swarmId> to monitor progress.

​
status

Read live state from .swarm/state.json, .swarm/agents/, .swarm/tasks/, and .swarm/coordination/ and render a progress dashboard. 
ruflo swarm status [swarmId]
The dashboard shows:
  • Overall progress — percentage bar derived from completed vs total tasks
  • Agent breakdown — active, idle, completed counts
  • Task breakdown — completed, in-progress, pending counts
  • Performance metrics — tokens used, average response time, success rate, elapsed time
  • Coordination — consensus rounds, messages sent, conflicts resolved

​
stop

Halt swarm execution. Updates .swarm/state.json with status: stopped and calls swarm_shutdown via MCP. 
ruflo swarm stop <swarmId> [options]
​
--force / -f
boolean
default:"false"
Skip the graceful drain and terminate agents immediately.
​
--save-state
boolean
default:"true"
Write final state to disk so the swarm can be resumed later.

​
scale

Add or remove agents from a running swarm. 
ruflo swarm scale <swarmId> --agents <n> [--type <type>]
​
--agents / -a
number
required
Target total agent count. Ruflo computes the delta against the current live count via swarm_status and spawns or terminates the difference.
​
--type / -t
string
Restrict scaling to a specific agent type (e.g. add only coder agents).

​
coordinate

Deploy and display the full V3 15-agent hierarchical-mesh roster, then initialize via MCP. 
ruflo swarm coordinate [--agents <n>]
​
--agents
number
default:"15"
Number of agents to activate (1–15). The roster is sliced from the top.
The V3 15-agent roster:
#RoleDomain
1Queen CoordinatorOrchestration
2Security ArchitectSecurity
3Security AuditorSecurity
4Test ArchitectSecurity
5Core ArchitectCore
6Memory SpecialistCore
7Swarm SpecialistCore
8Integration ArchitectIntegration
9Performance EngineerIntegration
10CLI DeveloperIntegration
11Hooks DeveloperIntegration
12MCP SpecialistIntegration
13Project CoordinatorManagement
14Documentation LeadManagement
15DevOps EngineerManagement

​
hive-mind spawn (high-level launcher)

For most use cases you don’t need to call swarm init and swarm start separately. hive-mind spawn is the one-liner that picks topology, deploys agents, and hands off to Claude Code: 
ruflo hive-mind spawn "<objective>"
Internally this is equivalent to running swarm init --topology hierarchical followed by swarm start --objective "<objective>" --strategy specialized.

​
Examples

# Initialize a hierarchical swarm
ruflo swarm init --topology hierarchical

# Start it with a development objective
ruflo swarm start -o "Build a REST API for user authentication" -s development

# Monitor progress
ruflo swarm status
For coding tasks, always use --topology hierarchical with --max-agents 8 and --strategy specialized. This configuration provides a single coordinator that validates each output against the goal, minimizing goal drift across long multi-agent sessions.
If swarm start cannot reach the MCP server, it still writes the state to .swarm/state.json but prints a warning. Start the MCP server first with ruflo mcp start for full coordination features.

Build docs developers (and LLMs) love

Get started for freeTalk to us