ruflo

The Problem

Teams that want Claude Code to operate as a coordinated swarm today must stitch together separate scripts, Docker images and CI pipelines. There is no single platform that provides agent lifecycle management, persistent memory, federated communication and enterprise‑grade security out of the box, so orchestration effort scales linearly with the number of agents.

What This Does

Ruflo is a portfolio of five self‑contained projects rather than a monolith:

Key capabilities are embodied in concrete artefacts:

• v3/plugins/agentic-qe/src/tools/security-compliance/detect-secrets.ts scans repositories for secret‑shaped patterns.
• archive/v2/bin/init/index.js and archive/v2/bin/init/rollback/index.js bootstrap and teardown a swarm environment.
• ruflo/ contains the CLI entry point that wire‑frames agent skills located under .agents/skills/*/SKILL.md.
• .agents/config.toml defines global coordination parameters (memory back‑end, comms layer).

The platform adds self‑learning swarm intelligence, federated messaging and native integration with Claude Code and Codex via plugins (@claude-flow/codex, @claude-flow/ruvector).

How It Is Wired

Execution starts at the CLI entry points:

1. ruflo CLI – invoked via npx ruvflo init ( documented in the root README). The command reads .agents/config.toml, registers each skill from .agents/skills/, and pushes configuration into .claude/.
2. Init/rollback scripts – archive/v2/bin/init/index.js creates the Docker‑based sandbox, mounts required volumes, and writes a starter memory.db (the committed dump flagged as a HIGH issue). archive/v2/bin/init/rollback/index.js tears down containers and removes temporary artefacts.
3. Skill dispatch – each .agents/skills/<name>/SKILL.md defines a callable function (usually a Node or Python entry). The orchestrator resolves the skill by name, injects the GITHUB_TOKEN (subject to the HIGH permission findings) and runs the function inside the sandbox.
4. RAG & model loading – v3/plugins/agentic-qe/ loads ONNX models (archive/v2/models/phi-4-mini/.../model.onnx) and uses detect-secrets.ts to filter inputs before they reach the LLM.

The call graph is shallow: CLI → config.toml → skill registry → skill function. No central event bus or stateful middleware exists; coordination is achieved through shared memory.db and environment variables. Cycles are limited to the skill‑registration loop, which is intentional and well‑scoped.

How To Use It

Setup

# Clone the repository (exact URL as provided)
git clone https://github.com/moses-y/ruflo.git

# Install the top‑level dependencies (pnpm is the declared package manager)
cd ruflo
pnpm install

# Bootstrap the swarm (creates initial config and registers skills)
npx ruvflo init

Configuration Required environment variables are defined in .agents/config.toml and .claude/. Key vars:

Running it

# Start the orchestration loop (foreground)
pnpm start   # defined in ruflo/package.json as `node dist/index.js`

The process reads the skill list, spins up any Docker containers referenced in archive/v2/benchmark/hive-mind-benchmarks/docker/, and begins accepting agent commands via the Claude Code CLI.

Real‑World Use

A typical deployment: a development team wants automatic PR‑title generation and security‑scan feedback on every pull request.

1. Init the swarm once (npx ruvflo init).
2. Configure a GitHub Action that triggers on pull_request and calls ruflo evaluate --pr <number>.
3. The orchestrator loads the code-review-swarm skill (.agents/skills/agent-code-review-swarm/SKILL.md), runs the model on the diff, and posts a comment.
4. detect-secrets.ts (v3) runs in parallel, flagging any leaked credentials before the LLM sees the code.

The result is a closed loop: code changes flow through a curated set of agents, each persisting useful state in memory.db and broadcasting results back to the PR.

Code Health & Issues

The static analysis produced 11 findings (0 critical, 4 high, 5 medium, 2 low). Reported verbatim:

• HIGH – Pin third‑party GitHub Actions to a commit SHA. Evidence: pnpm/action-setup@v2 in .github/workflows.
• HIGH – Discarding exit codes of failure‑sensitive steps. Evidence: lines 47 in .github/workflows/ci.yml.
• HIGH – Remove committed database dump. Evidence: archive/v2/docs/reasoningbank/models/domain-expert/memory.db.
• HIGH – Remove continue-on-error from correctness‑gating steps. Evidence: line 37 in .github/workflows/ci.yml.
• MEDIUM – Declare least‑privilege permissions for GITHUB_TOKEN. Evidence: 3 workflows with no permissions, 1 referencing secrets.
• MEDIUM – Pin container base image by digest. Evidence: archive/v2/benchmark/hive-mind-benchmarks/docker/Dockerfile uses node:18-bullseye-slim.
• MEDIUM – Move large binaries out of the repo (3 blobs >5 MB). Evidence: archive/v2/models/phi-4-mini/.../model.onnx (49.7 MB), model.onnx.data (42.7 MB), ruflo-plugins.gif (5.3 MB).
• MEDIUM – Set persist-credentials: false on checkout. Evidence: checkout step in .github/workflows/ci.yml.
• MEDIUM – Add a non‑root USER to the Docker image. Evidence: Dockerfile has no USER directive.
• LOW – Set timeout-minutes on workflow jobs. Evidence: 3 jobs in .github/workflows/integration-tests.yml have no timeout.

No additional issues are introduced; the above constitute the complete measured set.

The Bottom Line

Ruflo delivers a concrete, file‑level orchestration layer for Claude Code, with clear entry points, a modest skill registry and a security‑first plugin (detect‑secrets). The repo’s multi‑project structure means you can adopt only the pieces you need (e.g., just the init/rollback scripts or the v3 security tools). However, the findings highlight real CI‑security gaps—especially mutable GitHub Action SHAs, leaked DB dumps and overscoped token permissions—that should be addressed before production use. Teams comfortable patching these hygiene items will gain a functional multi‑agent system; others may need to evaluate a more opinionated platform.