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.

Monitoring tools give real-time visibility into swarm state, agent performance, task queue progress, and background worker execution. All monitoring tools are read-only and safe to call at any frequency — they query the coordination ledger maintained by Ruflo’s daemon without affecting running agents or tasks.

​
swarm_status

Get the current state of an active swarm including its topology, active agent count, pending task queue, consensus state, and uptime.
​
swarmId
string
The swarm to query. If omitted, returns a summary of all active swarms.
​
swarmId
string
Unique swarm identifier.
​
topology
string
Active topology: hierarchical, mesh, ring, or star.
​
activeAgents
number
Number of agents currently spawned and active in the swarm.
​
taskQueue
object
Task queue breakdown: { pending, running, completed, failed }.
​
consensusState
string
Current consensus state: stable, electing, or split. A split state indicates agents are failing to reach consensus and may need intervention.
​
uptime
number
Swarm uptime in seconds since swarm_init.
// Response example
{
  "swarmId": "swarm-abc123",
  "topology": "hierarchical",
  "activeAgents": 4,
  "maxAgents": 8,
  "taskQueue": {
    "pending": 2,
    "running": 3,
    "completed": 18,
    "failed": 1
  },
  "consensusState": "stable",
  "consensusAlgorithm": "raft",
  "uptime": 3842,
  "objective": "Implement OAuth 2.0 authentication flow"
}

​
agent_list

List all agents with their types, current status, and assigned tasks. Use this to identify idle agents available for new work or to spot agents that have stalled.
​
swarmId
string
Filter results to agents belonging to a specific swarm. Omit to list all agents across all active swarms.
​
status
string
Filter agents by current status.
  • active — Currently executing a task
  • idle — Spawned and waiting for work
  • stopped — Gracefully terminated
// Response example
[
  {
    "agentId": "agent-coder-7f2a",
    "name": "auth-coder",
    "type": "coder",
    "swarmId": "swarm-abc123",
    "status": "active",
    "currentTask": "task-jw8x",
    "tasksCompleted": 3,
    "spawnedAt": "2025-01-15T10:30:05Z"
  },
  {
    "agentId": "agent-tester-9b1c",
    "name": "test-1",
    "type": "tester",
    "swarmId": "swarm-abc123",
    "status": "idle",
    "currentTask": null,
    "tasksCompleted": 2,
    "spawnedAt": "2025-01-15T10:30:07Z"
  }
]

​
agent_metrics

Get detailed performance metrics for a specific agent. Useful for identifying slow agents, high failure rates, or unusual token consumption patterns.
​
name
string
required
The agent name as returned by agent_list or agent_spawn.
​
tasksCompleted
number
Total number of tasks the agent has completed since spawning.
​
avgTaskTime
number
Average task completion time in milliseconds.
​
successRate
number
Task success rate (0–1). Values below 0.7 may indicate the agent type is mismatched to the tasks it is receiving.
​
tokenUsage
object
Cumulative token usage: { inputTokens, outputTokens, totalTokens, estimatedCostUSD }.
​
lastActive
string
ISO 8601 timestamp of the agent’s most recent activity.
// Tool call
{ "name": "auth-coder" }

// Response
{
  "agentId": "agent-coder-7f2a",
  "name": "auth-coder",
  "type": "coder",
  "tasksCompleted": 7,
  "avgTaskTime": 4200,
  "successRate": 0.93,
  "tokenUsage": {
    "inputTokens": 84200,
    "outputTokens": 31500,
    "totalTokens": 115700,
    "estimatedCostUSD": 0.34
  },
  "lastActive": "2025-01-15T11:08:42Z"
}

​
task_status

Get the current status and progress of a specific task by its ID.
​
taskId
string
required
The task identifier as returned by task_orchestrate.
​
taskId
string
Task identifier.
​
status
string
Current task status: queued, assigned, running, completed, or failed.
​
assignedAgent
string
Name of the agent currently executing or that last executed the task.
​
progress
number
Estimated completion percentage (0–100), if reported by the executing agent.
​
startTime
string
ISO 8601 timestamp when the task began execution.
​
estimatedCompletion
string
ISO 8601 estimated completion timestamp based on average task duration for this agent type. Absent for queued tasks.
// Tool call
{ "taskId": "task-jw8x" }

// Response
{
  "taskId": "task-jw8x",
  "description": "Implement JWT token validation middleware with refresh token support",
  "status": "running",
  "assignedAgent": "auth-coder",
  "priority": "high",
  "progress": 65,
  "startTime": "2025-01-15T10:30:12Z",
  "estimatedCompletion": "2025-01-15T10:35:30Z"
}

​
Background Worker Tools

Ruflo runs 12 background workers that fire automatically based on context triggers (file changes, session events, performance thresholds). The worker tools give you visibility into their execution and let you trigger them manually.

​
Worker Types

WorkerTriggerWhat It Does
ultralearnFirst session in new codebaseDeep knowledge acquisition across the whole project
optimizeOperation takes > 2sSurfaces performance improvement suggestions
consolidateEvery 30 min or session endMerges and deduplicates memory entries
predictSimilar task seen beforePreloads likely resources into cache
auditChanges to auth/crypto filesRuns a security vulnerability scan
mapNew directories createdUpdates codebase structure mapping
preloadCache miss on frequent patternsWarms the LRU cache
deepdiveFile > 500 lines editedDeep code analysis and annotation
documentNew functions or classes addedGenerates or updates documentation
refactorDuplicate code detectedProduces refactoring suggestions
benchmarkPerformance-critical changesRuns performance benchmarks
testgapsCode changes without testsIdentifies missing test coverage

​
worker/run

Trigger a background worker manually without waiting for its context trigger.
​
worker
string
required
Worker name from the table above.
​
context
string
Path or description of the context to run the worker against.
# Manually trigger a security audit on the auth module
npx ruflo@latest hooks worker dispatch --trigger audit --context "./src/auth"

​
worker/status

Get the current status of the worker pool: which workers are running, queued, or idle. 
// Response example
{
  "activeWorkers": ["audit", "consolidate"],
  "queuedWorkers": [],
  "idleWorkers": ["ultralearn", "optimize", "predict", "map", "preload", "deepdive", "document", "refactor", "benchmark", "testgaps"],
  "completedToday": 14,
  "lastDispatch": "2025-01-15T11:02:00Z"
}

​
worker/alerts

Get alerts triggered by worker execution. Workers emit alerts when they detect actionable findings (security vulnerabilities, coverage gaps, performance regressions). 
// Response example
[
  {
    "alertId": "alert-7x2b",
    "worker": "audit",
    "severity": "high",
    "message": "Potential JWT secret hardcoded in src/config.ts:14",
    "context": "./src/config.ts",
    "triggeredAt": "2025-01-15T11:03:45Z",
    "acknowledged": false
  }
]

​
worker/history

Get the execution history of all background workers with timing and outcome data. 
# List all workers and their last run status
npx ruflo@latest hooks worker list

# Check worker status
npx ruflo@latest hooks worker status

​
Model Routing Observability

Ruflo’s Thompson sampling model router (Haiku / Sonnet / Opus) records routing decisions that you can query for cost and accuracy analysis. 
# View routing statistics and cost savings
npx ruflo@latest hooks model-stats

# See why a task was routed to a specific model
npx ruflo@latest hooks model-route --task "fix typo in README"
# → Recommends: haiku (simple task, low complexity, cost: $0.0001)

npx ruflo@latest hooks model-route --task "design distributed consensus system"
# → Recommends: opus (complex architecture, high reasoning required)
The router self-corrects after approximately 50 routing outcomes. Early sessions may not reflect optimal routing; routing accuracy improves automatically as the Beta(α, β) priors converge.

Build docs developers (and LLMs) love

Get started for freeTalk to us