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.

Coordination tools manage the entire swarm lifecycle: initializing a topology, spawning typed agents into it, assigning tasks, and tearing down when work is complete. All coordination calls return instantly — they write state records that the learning loop and monitoring tools consume. The executor (Claude Code or Codex) continues working immediately after each call.

​
swarm_init

Initialize a new agent swarm for coordinated task execution. This is typically the first tool call in any multi-agent session. The returned swarmId is passed to subsequent agent_spawn and task_orchestrate calls.
​
topology
string
default:"hierarchical"
Swarm topology. Controls how agents communicate and share context.
  • hierarchical — Queen-led. Strategic queen directs tactical queens which direct worker agents. Best for large, structured tasks.
  • mesh — Peer-to-peer. All agents communicate directly. Best for parallel, loosely coupled tasks.
  • ring — Agents pass context in a ring. Best for pipeline-style workflows.
  • star — Centralized coordinator with spoke workers. Best for tasks requiring a single point of coordination.
​
maxAgents
number
default:"8"
Maximum number of agents in the swarm. Additional spawn requests above this limit are queued until a slot opens.
​
consensus
string
default:"raft"
Consensus algorithm for fault-tolerant decision-making when agents disagree.
  • raft — Leader-elected majority. Best general-purpose choice.
  • byzantine — Tolerates up to f < n/3 malicious or faulty agents. Use when correctness is critical.
  • gossip — Eventually consistent, low overhead. Best for large swarms where strict consistency is not required.
​
objective
string
Optional high-level task objective stored in the swarm record. Surfaced in swarm_status output and used by the intelligence loop to match patterns.
// Tool call
{
  "topology": "hierarchical",
  "maxAgents": 6,
  "consensus": "raft",
  "objective": "Implement OAuth 2.0 authentication flow"
}

// Response
{
  "swarmId": "swarm-abc123",
  "status": "initialized",
  "topology": "hierarchical",
  "consensus": "raft",
  "agents": [],
  "createdAt": "2025-01-15T10:30:00Z"
}

​
agent_spawn

Spawn a specialized agent within an existing swarm. Each agent type carries a pre-trained skill set. Spawning is fast — the call registers the agent in the coordination ledger and returns immediately.
​
type
string
required
Agent specialization. Determines which skills and routing patterns apply.
TypePurpose
coderWrites, refactors, and debugs code
testerGenerates and runs test suites
reviewerPerforms code review and quality checks
architectDesigns system structure and ADRs
securityRuns vulnerability scans and threat modeling
docsGenerates and maintains documentation
coordinatorOrchestrates other agents in the swarm
researcherAnalyzes requirements and investigates unknowns
​
name
string
Human-readable agent name. Used in monitoring output and memory namespacing. If omitted, Ruflo generates a name like coder-7f2a.
​
swarmId
string
Swarm to join. If omitted, the agent is spawned without a swarm and operates independently. Pass the swarmId returned by swarm_init to add the agent to a coordinated swarm.
​
model
string
LLM model override for this specific agent. Useful for routing expensive architecture work to claude-opus while keeping coder agents on claude-haiku for cost efficiency. If omitted, the Thompson sampling model router selects the best tier automatically.
// Tool call
{
  "type": "coder",
  "name": "auth-coder",
  "swarmId": "swarm-abc123"
}

// Response
{
  "agentId": "agent-coder-7f2a",
  "name": "auth-coder",
  "type": "coder",
  "swarmId": "swarm-abc123",
  "status": "idle",
  "spawnedAt": "2025-01-15T10:30:05Z"
}

​
task_orchestrate

Assign and orchestrate a task across swarm agents. The coordinator routes the task to the most suitable idle agent based on type preference, current load, and learned routing patterns from the intelligence loop.
​
task
string
required
Natural language task description. The intelligence loop uses this for semantic matching against stored patterns — more descriptive descriptions produce better routing.
​
swarmId
string
Target swarm. The task is distributed among the swarm’s agents according to the swarm’s topology and consensus rules.
​
agentType
string
Preferred agent type for this task. If an agent of this type is idle in the swarm, it receives the task first. Falls back to the best available agent if the preferred type is busy.
​
priority
string
default:"normal"
Task priority in the queue.
  • low — Processed after all normal and high priority tasks
  • normal — Default queue position
  • high — Jumps ahead of normal priority tasks
  • critical — Processed immediately, may preempt running tasks
// Tool call
{
  "task": "Implement JWT token validation middleware with refresh token support",
  "swarmId": "swarm-abc123",
  "agentType": "coder",
  "priority": "high"
}

// Response
{
  "taskId": "task-jw8x",
  "status": "assigned",
  "assignedAgent": "auth-coder",
  "priority": "high",
  "queuePosition": 0,
  "estimatedStart": "2025-01-15T10:30:10Z"
}

​
swarm_stop

Stop a running swarm and gracefully terminate its agents. In-progress tasks are checkpointed to memory before shutdown.
​
swarmId
string
required
The swarm to stop.
​
persistPatterns
boolean
default:"true"
When true, successful task patterns are written to the memory store before shutdown so the intelligence loop can reuse them in future sessions.

​
Multi-Agent Recipe: Feature Implementation

The following sequence is a copy-paste-ready pattern for a 4-agent feature build. Spawn agents first, then immediately begin your own implementation — do not wait for coordination calls to “do the work.” 
# 1. Initialize the swarm
npx ruflo@latest swarm init --topology hierarchical --max-agents 8

# 2. Spawn specialized agents
npx ruflo@latest agent spawn --type architect --name arch-1
npx ruflo@latest agent spawn --type coder --name impl-1
npx ruflo@latest agent spawn --type coder --name impl-2
npx ruflo@latest agent spawn --type tester --name test-1
npx ruflo@latest agent spawn --type reviewer --name review-1

# 3. YOU (Claude Code / Codex) do the actual implementation work

# 4. Report completion
npx ruflo@latest memory store --key "oauth-pattern" --value "JWT + refresh tokens in middleware" --namespace patterns
For V3 full-coordination mode with 15 agents and automatic role assignment, use npx ruflo@latest swarm init --v3-mode. This spawns strategic, tactical, and adaptive queen agents alongside the worker pool automatically.

Build docs developers (and LLMs) love

Get started for freeTalk to us