Ruv Swarm

ruv-swarm

Neural swarm orchestration engine with WebAssembly-accelerated agent coordination, topology management, and distributed task execution. Orchestrate multi-agent swarms with configurable topologies, consensus protocols, load balancing, and self-healing capabilities.

Quick Command Reference

Installation

Install: npx ruv-swarm@latest See Installation Guide for the full ecosystem.

Core Commands

init

Initialize a swarm configuration in the current directory.

npx ruv-swarm@latest init [--topology <type>] [--max-agents <n>] [--force]

Options: --topology <type> (mesh, hierarchical, ring, star), --max-agents <n>, --strategy <name> (specialized, generalist, adaptive), --force

spawn

Spawn agents into the swarm.

npx ruv-swarm@latest spawn --count <n> [--type <agent-type>] [--gpu]

Options: --count <n>, --type <agent-type>, --model <name>, --gpu, --memory <mb>

start

Start the swarm orchestrator.

npx ruv-swarm@latest start [--config <path>] [--daemon]

status

Show current swarm status including agent health, task progress, and topology.

npx ruv-swarm@latest status [--format json] [--watch]

task

Task management for the swarm.

npx ruv-swarm@latest task run --file <path>
npx ruv-swarm@latest task list [--status <type>]
npx ruv-swarm@latest task cancel <task-id>

agents

Agent management.

npx ruv-swarm@latest agents list [--format json]
npx ruv-swarm@latest agents info <agent-id>
npx ruv-swarm@latest agents terminate <agent-id>
npx ruv-swarm@latest agents scale --count <n>

topology

Swarm topology management.

npx ruv-swarm@latest topology set <type>
npx ruv-swarm@latest topology info
npx ruv-swarm@latest topology optimize

bench

Benchmark swarm performance.

npx ruv-swarm@latest bench [--iterations <n>] [--agents <n>]

stop

Stop the swarm and all agents.

npx ruv-swarm@latest stop [--graceful] [--timeout <ms>]

Programmatic API

import { Swarm, Agent, Topology } from 'ruv-swarm';

// Create swarm
const swarm = new Swarm({
  topology: 'mesh',
  maxAgents: 10,
  strategy: 'specialized',
  consensus: 'raft',
});

// Spawn agents
await swarm.spawn({ count: 5, type: 'coder' });

// Submit task
const result = await swarm.submit({
  type: 'code-review',
  payload: { files: ['src/auth.ts'] },
  timeout: 30000,
});

// Get status
const status = await swarm.status();
console.log(`Active agents: ${status.agents.length}`);
console.log(`Pending tasks: ${status.tasks.pending}`);

// Coordinate with consensus
const consensus = await swarm.consensus({
  proposal: 'merge-branch',
  threshold: 0.67,
});

// Shutdown
await swarm.stop({ graceful: true });

Common Patterns

Hierarchical Code Review Swarm

npx ruv-swarm@latest init --topology hierarchical --max-agents 8
npx ruv-swarm@latest spawn --count 3 --type reviewer
npx ruv-swarm@latest spawn --count 1 --type coordinator
npx ruv-swarm@latest task run --file review-task.json

Adaptive Scaling

npx ruv-swarm@latest start --daemon
npx ruv-swarm@latest agents scale --count 10
npx ruv-swarm@latest topology optimize
npx ruv-swarm@latest status --watch

RAN DDD Context

Bounded Context: Agent Orchestration

References

• Command reference: See references/commands.md
• Full README
• npm