ruv-swarm

ruv-swarm for Node.js

A JavaScript API and command-line tool for coordinating agents, storing task state in SQLite, and calling the repository's WebAssembly modules. It includes a stdio MCP server for clients such as Claude Code.

Install

Use Node.js 22.13 or newer, Python 3 and a C++20 build toolchain. The checkout builds its SQLite addon from verified source: published Node wrappers still bundle an older affected SQLite. Installation pins the compatible better-sqlite3 12.11.1 wrapper and builds SQLite 3.54.1 from an archive and file hashes recorded in scripts/sqlite-source.json. It honors the host proxy and CA settings; unverified/default prebuilt binaries cannot open application databases.

npm install ruv-swarm
npx ruv-swarm --help
npx ruv-swarm --version

Pin the version you have tested in applications and MCP client configurations. The npm package and Rust crates have separate version numbers.

The package installs one binding per platform, architecture and Node ABI under native/sqlite/. Database construction checks its receipt, source/binary hashes, ABI and actual sqlite_version()/sqlite_source_id() using a private memory DB before opening a user file. Rebuild after changing Node ABI:

npm run build:sqlite
node scripts/sqlite-build.mjs --verify

--ignore-scripts installations can use the independent WASM exports and help commands. Database-backed commands report an actionable error until the patched source build succeeds. The builder never substitutes a vulnerable prebuilt addon after a build failure. Root workspace installation builds the workspace package, then verifies the result from its root lifecycle hook.

Start the MCP server

npx ruv-swarm mcp start

Configure your client to launch that command using stdio. For example:

{
  "mcpServers": {
    "ruv-swarm": {
      "command": "npx",
      "args": ["ruv-swarm", "mcp", "start"]
    }
  }
}

Use ruv-swarm mcp tools to list tools. The WebSocket server is not implemented in this distribution.

The server exposes 17 supported tools for persisted local metadata, dense inference, statistical forecasts, memory observations, and measured local benchmarks. Missing tasks return errors. MCP training tools, autonomous DAA execution, learned-pattern analysis, and external model execution are unavailable and return explicit errors. The JavaScript API below separately exposes dense autograd training.

The server accepts newline-delimited JSON-RPC. Each frame is limited to 1 MiB of UTF-8 data, and each process accepts up to 32 pending requests. Outgoing frames have the same limit; slow clients have a bounded 4 MiB reply queue. Closing stdin drains pending replies before shutdown. Oversized frames are discarded through the next newline so subsequent requests can still be handled. Local metadata is limited to 64 swarms, 1,000 agents, and 10,000 tasks per database; exceeding a limit fails explicitly. Monitoring records at most 100 aggregate snapshots per call. Keep access to the process and its SQLite files limited to the users who should control those agents.

Train a small network through WASM

The checkout's JavaScript API runs the shared Rust reverse-mode engine:

import { RuvSwarm } from 'ruv-swarm';
const runtime = await RuvSwarm.initialize({ useSIMD: true });
const json = JSON.stringify({ schema: 'ruv-fann.dense-layers/1', layers: [
  { inputs: 1, outputs: 1, weights: [0], bias: [0], activation: 'Linear', steepness: 1 },
] });
const model = runtime.createTrainableNetwork(json, 2);
const loss = model.mse_backward(Float64Array.of(1, 2), Float64Array.of(2, 4), 2);
console.log(loss, model.parameter_gradients()); // 10; [-10, -6]
model.sgd_step(0.1);
const prepared = model.prepare();
model.free();
console.log(prepared.run(Float64Array.of(2))); // [2.6]
prepared.free();

For AdamW, call configure_adamw(lr, beta1, beta2, epsilon, weightDecay) once, then alternate mse_backward and adamw_step. Each step consumes its gradients. Changing parameters through SGD requires resetting AdamW. Returned predictions and parameter/input gradient arrays are owned copies. to_dense_layers_json() checkpoints topology and weights; it does not serialize optimizer moments.

Training supports Linear, Sigmoid, Tanh, SigmoidSymmetric and ReLU in Float64. JSON is limited to 4 MiB UTF-8 and 64 layers. Capacity is 1–4096 rows, combined requested training storage is at most 64 MiB, and conservative per-call work counts are capped. Pass ordinary JS-owned Float64Arrays; shared, detached and WASM-memory views are rejected. Setup, returned array copies and JSON export allocate; repeated backward and optimizer calls reuse Rust numerical buffers.

For inference-only Candle exports, use runtime.createDensePreparedNetwork(json). Browsers import WasmTrainableNetwork and WasmPreparedNetwork directly from the generated bindings. The optional native Node package uses napi-rs to run the same core. See the Candle adapter for actual tensor export and independent CPU gradient tests.

Run commands

npx ruv-swarm init mesh 5
npx ruv-swarm spawn researcher "Research agent"
npx ruv-swarm status

ruv-swarm init --claude writes supported tool documentation and a project .mcp.json registration. It preserves existing MCP servers, permissions and hooks. Review those files before adding hooks to your development environment.

The coordination layer tracks work and invokes available modules. Creating an agent does not, by itself, establish that an external model has performed a task. Features depend on the compiled WASM artifact and the APIs it exports.

Invoke Claude Code

npx ruv-swarm claude-invoke "Summarize this project's architecture"

Claude's normal permission checks remain enabled by default. Prompts are passed as literal process arguments, so quotes and shell syntax are ordinary text. To explicitly disable permission checks for an invocation, use the --dangerously-skip-permissions flag. The internal integration helper preserves its secure: false opt-in; the supported package entry point does not export that helper.

Use claude-invoke -- "prompt" when a prompt starts with a flag. Generated bash helpers also separate options from prompt text. The former Windows batch prompt helper fails explicitly; use the Node CLI to preserve literal arguments.

Use the JavaScript API

The package entry point exports RuvSwarm. It loads the bundled WASM module and wraps its local assignment APIs:

import { RuvSwarm } from 'ruv-swarm';

const runtime = await RuvSwarm.initialize();
const swarm = await runtime.createSwarm({
  name: 'example', topology: 'mesh', maxAgents: 3
});
console.log(swarm.getStatus());
swarm.free();

swarm.spawn({type, name, capabilities}) records an agent. swarm.orchestrate({description, requiredCapabilities}) assigns matching idle agents and returns assigned or unassigned. It does not execute an external model. agent.execute() rejects until an external executor exists; agent.reset() returns an assigned agent to idle. Release the swarm with free() when finished.

The runtime also exposes dense neural inference and three one-step statistical forecasts:

const network = runtime.createNeuralNetwork([2, 1], 'Linear');
network.set_weights(Float64Array.of(2, -1));
console.log(network.run(Float64Array.of(3, 4))); // Float64Array [2]
network.free();

const forecast = runtime.createForecastingModel('linear'); // also 'mean' or 'naive'
console.log(forecast.predict(Float64Array.of(1, 3, 5))); // Float64Array [7]
forecast.free();

The same operations are available through the CLI:

ruv-swarm neural infer --layers 2,1 --weights 2,-1 --input 3,4
ruv-swarm neural forecast --model linear --input 1,3,5
ruv-swarm benchmark run --iterations 1000

Neural network dimensions and inputs must have the exact expected shape and finite numbers. Forecast names such as LSTM and Transformer are unsupported. See src/index.d.ts for the facade's types. Historical prototype files are outside the public export map; applications should use this facade.

Reuse prepared inference

After setting weights, prepare an independent snapshot. It keeps working after the source network is edited or freed:

const network = runtime.createNeuralNetwork([2, 1], 'Linear');
network.set_weights(Float64Array.of(2, -1));
const prepared = network.prepare();
network.free();
try {
  const input = Float64Array.of(3, 4);
  const output = new Float64Array(1);
  prepared.run_into(input, output);
  console.log(output); // Float64Array [2]
  console.log(prepared.input_size, prepared.output_size, prepared.estimated_bytes);
} finally {
  prepared.free();
}

run_into(input, output) reuses Rust numeric storage and writes to the supplied output array. run(input) returns a new output array. Both require real Float64Array inputs with the exact dimensions and finite values. Shared buffers and views into this module's WASM memory are rejected. Invalid inputs or numeric overflow leave the caller's output unchanged. The binding still copies values and creates temporary JavaScript views; buffer reuse does not eliminate the cost of crossing into WASM.

To run a trained Rust model, export Network<f64> with serde_json::to_string(&network) and pass that string to runtime.createPreparedNetwork(networkJson). Native sparse and reordered connections and all 21 native activation variants are supported. Browser callers use WasmPreparedNetwork.from_network_json(networkJson) on the generated class. Inference evaluates in Float64. Import JSON is limited to 4 MiB of UTF-8. Preparation permits an estimated 64 MiB for packed parameters, workspace and input/output staging. This estimate excludes the original model, temporary conversion graph and allocator bookkeeping; it is not a peak-memory guarantee.

Process multiple rows per call

A fixed-capacity batch reduces repeated JavaScript/WASM calls and reuses its numeric buffers. Rows are laid out consecutively in each Float64Array:

const network = runtime.createNeuralNetwork([2, 1], 'Linear');
network.set_weights(Float64Array.of(2, -1));
const prepared = network.prepare();
const batch = prepared.create_batch(32);
prepared.free();
network.free();
try {
  const inputs = Float64Array.of(3, 4, 5, 6, 7, 8); // three input rows
  const outputs = new Float64Array(3);
  batch.run_into(inputs, outputs, 3);
  console.log(outputs); // Float64Array [2, 4, 6]
  console.log(batch.max_rows, batch.estimated_bytes);
} finally {
  batch.free();
}

The batch shares immutable weights with its parent and owns its workspace. It stays valid after its parent is freed. Recreate it after changing trained weights. Capacity must be an integer from 1 to 4,096; each call may use fewer rows. Zero rows with empty, valid Float64Arrays is a no-op. Invalid dimensions, non-finite numbers, numeric overflow or an invalid later row leave the whole caller output unchanged. The same hostile-buffer checks as single inference remain active. No raw WASM memory views are exposed.

Each batch has a 64 MiB estimated working-storage ceiling, including its shared snapshot, workspace, numeric staging, cached checks and Rust handle overhead. This is not a process-memory limit. Large models may allow fewer rows. Construction and calls also enforce a 100-million work-unit ceiling. Per-row units count twice the connections, three times the evaluated neurons, twice the input/output widths, plus bias nodes and layers. Disconnected neurons