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.

Agents are the workers inside every Ruflo swarm. Each agent is typed, specialised, and managed — typed because it carries a declared capability (coder, tester, architect, etc.), specialised because its system prompt and tool allowlist are tuned for exactly that role, and managed because the swarm coordinator is responsible for spawning, monitoring, and retiring agents automatically as work arrives. You interact with agents either through the CLI, the MCP server from Claude Code, or by letting the hive-mind handle everything for you.
Most users never need to spawn agents manually. After npx ruflo init, the hive-mind spawns and retires the right agents automatically every time you run a task through Claude Code or the CLI. The commands below exist for fine-grained control when you need it.

​
Agent Types

Ruflo ships agents across eight categories. Key types and their roles:
TypeCategoryPurpose
coderCore DevelopmentWrites and modifies code; primary implementation agent
testerCore DevelopmentGenerates tests, runs coverage analysis, detects test gaps
reviewerCore DevelopmentCode review, style checks, PR feedback
architectCore DevelopmentSystem design, ADR authoring, bounded-context planning
researcherCore DevelopmentGathers context, reads docs, summarises findings
docsCore DevelopmentDocumentation generation and drift detection
devopsCore DevelopmentCI/CD workflow automation and infrastructure management
analyzerCore DevelopmentCode analysis, pattern detection, and context extraction
queen-coordinatorV3 SpecialisedHierarchical orchestrator; validates all worker outputs against the goal
securityV3 SpecialisedVulnerability scanning, CVE triage, prompt injection analysis
security-architectV3 SpecialisedSecurity design, threat modelling, compliance review
memory-specialistV3 SpecialisedMemory optimisation, HNSW tuning, embedding pipeline management
hierarchical-coordinatorSwarm CoordinationManages queen-worker topology
mesh-coordinatorSwarm CoordinationPeer-to-peer coordination in a mesh topology
adaptive-coordinatorSwarm CoordinationReal-time topology switching based on workload signals
byzantine-coordinatorConsensus & DistributedFault-tolerant coordination when some agents may fail or return bad data
raft-managerConsensus & DistributedLeader-based state management; no conflicting decisions
perf-analyzerPerformanceProfiling, bottleneck detection, optimisation suggestions
pr-managerGitHub & RepositoryPR creation, description generation, reviewer assignment
backend-devSpecialised DevBackend service implementation
ml-developerSpecialised DevML pipeline and model integration work
cicd-engineerSpecialised DevCI/CD workflow automation

​
Agent Lifecycle

Every agent moves through four states:
1

Spawn

The swarm coordinator (or a direct CLI/MCP call) creates the agent, assigns it a unique ID, loads its capability profile, and registers it in the AgentPool. The agent is now live but not yet processing work.
2

Active

The agent has been assigned a task and is running. It can call LLM providers, read and write memory, coordinate with peer agents over the message bus, and fire hooks.
3

Idle

The agent has finished its current task and is waiting for the next assignment. Idle agents are kept alive for idleTimeoutMs (default 5 minutes) before the pool reclaims them, reducing the cost of re-spawning for hot workloads.
4

Stopped

The agent has been explicitly stopped, its idle timeout expired, or the swarm was shut down. Its in-flight memory is flushed and its entry is removed from the registry.

​
Spawning Agents via CLI

# Spawn a coder agent with a custom name
npx ruflo@latest agent spawn --type coder --name my-coder

# Spawn a second agent for test writing
npx ruflo@latest agent spawn --type tester --name test-runner

# List all active agents and their status
npx ruflo@latest agent list

# Check the status of a specific agent
npx ruflo@latest agent status --name my-coder

# Stop an agent cleanly
npx ruflo@latest agent stop --name my-coder

​
Agent Pool Management

The AgentPool manages the full agent lifecycle automatically. It maintains a minimum number of warm agents, scales up when the queue grows, and reclaims idle agents to free memory. 
# Inspect the current pool state (sizes, utilisation, pending tasks)
npx ruflo@latest agent pool
Key pool configuration values (set in claude-flow.config.json or via npx ruflo config set):
SettingDefaultDescription
minAgents1Agents kept warm even when idle
maxAgents15Hard ceiling for the pool
idleTimeoutMs300000 (5 min)How long an idle agent lives before reclaim
The pool respects the maxAgents boundary strictly — it will queue tasks rather than spawn beyond the limit. For large parallel workloads, raise maxAgents in your swarm configuration.

​
Metrics and Health

# Per-agent performance metrics (tasks completed, latency, token usage)
npx ruflo@latest agent metrics --name my-coder

# Health check across all active agents
npx ruflo@latest agent health
Metrics are also available via the MCP tools (see below) so they can be queried directly from a Claude Code session.

​
MCP Tools for Agents

When Ruflo is registered as an MCP server, Claude Code can call agent tools directly during a session:
ToolDescription
agent_spawnSpawn a new agent of a given type and name
agent_listList all active agents with their current status
agent_metricsRetrieve per-agent performance metrics by name
Use agent_spawn to start a security agent named "sec-audit", 
then run agent_metrics on it after the scan completes.
These tools are part of the 313 MCP tools registered by npx ruflo@latest mcp start. They are not available when using the lightweight Claude Code Plugin path — you need the full CLI install (npx ruflo init) for MCP tools to work.

Build docs developers (and LLMs) love

Get started for freeTalk to us