Ruflo en bref : un moteur multi-agents qui s’auto-améliore

Présentation du projet

Ruflo est une couche d’orchestration multi-agents pensée pour Claude Code. En une phrase, son objectif est le suivant : transformer Claude Code de “simple assistant de questions/réponses” en une équipe d’IA capable de collaborer, de mémoriser et de s’auto-évoluer.

À l’origine, Ruflo s’appelait Claude Flow, développé par RuvNet (le fondateur a un background Rust ; le nom combine l’imagerie de Ruv + flow). Le noyau WASM, écrit en Rust, gère le moteur de stratégie, les embeddings vectoriels et le système de preuves, afin de garantir des performances élevées. La dernière version stable [email protected] est déjà un produit complet prêt pour l’entreprise :

• 300+ outils MCP injectés directement dans Claude Code
• 60+ rôles d’Agent spécialisés (coder, tester, architect, security-architect…)
• Mémoire auto-apprenante : AgentDB + index vectoriel HNSW ; la recherche est 150× à 12,500× plus rapide qu’un brute-force
• Collaboration fédérée multi-machines : Agent Federation, communication zero-trust basée sur mTLS + ed25519
• Capacité d’auto-évolution : module d’apprentissage neuronal SONA, extraction de motifs à partir des trajectoires historiques et optimisation continue
• 32 plugins couvrant la sécurité, le suivi des coûts, l’automatisation du navigateur, l’intégration GitHub, etc.

Sa philosophie de conception est particulièrement intéressante : une fois installé, vous n’avez pas besoin d’apprendre 300 outils MCP. La couche de routage via Hooks distribue automatiquement la tâche au bon Agent. Vous continuez à coder, et Ruflo coordonne tout en arrière-plan.

Difficulté / Durée / Résultats

• Difficulté : ★★☆☆☆ (install + démarrage en 5 minutes)
• Durée : environ 20 minutes
• Résultats : comprendre les topologies swarm et la gestion du cycle de vie, saisir le principe de la mémoire vectorielle HNSW, et apprendre à faire communiquer les Agents entre eux via SendMessage

Profil des lecteurs visés

• Développeurs avec 1 à 5 ans d’expérience
• Qui veulent faire passer l’IA de “outil de discussion” à “équipe qui réalise le travail”
• Développeurs individuels ou petites équipes qui utilisent déjà (ou prévoient d’utiliser) Claude Code pour le développement

Dépendances clés et environnement

Arborescence complète du projet

ruflo/
├── bin/
│   ├── cli.js              # Point d’entrée CLI (commande Ruflo)
│   └── mcp-server.js       # Serveur MCP
│
├── v3/@claude-flow/        # Package du module cœur
│   ├── cli/                # 26 commandes de haut niveau (140+ sous-commandes)
│   ├── memory/             # AgentDB + recherche vectorielle HNSW
│   ├── swarm/              # Coordinateur unifié (mesh hiérarchique à 15 agents)
│   ├── security/           # Corrections CVE, validation d’entrée, sécurité des chemins
│   ├── neural/             # Module d’auto-apprentissage SONA
│   ├── hooks/              # 17 hooks + 12 workers en arrière-plan
│   ├── guidance/           # Plan de gouvernance (compile/enforce/prove/evolve)
│   └── shared/             # Types, événements, interfaces essentielles
│
├── plugins/                # 32 plugins officiels
│   ├── ruflo-core/         # Base (serveur, health check, découverte de plugins)
│   ├── ruflo-swarm/        # Coordination d’équipes multi-agents
│   ├── ruflo-federation/   # Collaboration sécurisée multi-machines
│   ├── ruflo-agentdb/      # Mémoire vectorielle
│   ├── ruflo-intelligence/ # Motifs neuronaux auto-apprenants
│   └── ...                 # Les 27 autres plugins
│
├── .claude/                # Configuration de Claude Code (serveur MCP, settings.json)
├── .agents/                # Définition des compétences des agents ($skill-name)
└── mcp/                    # Définition des outils MCP (agent-tools.ts, memory-tools.ts, etc.)

Guide pas à pas (hands-on)

Étape 1 : Installation en une seule commande

Une seule ligne suffit pour initialiser le tout, avec un assistant de configuration guidé :

npx ruflo@latest init --wizard

Cette commande effectue successivement :

1. Génère CLAUDE.md dans le répertoire courant et y écrit les règles de routage des Hooks
2. Enregistre le serveur MCP dans la configuration de Claude Code
3. Dans .claude-flow/, écrit la configuration par défaut et le fichier d’amorçage mémoire

Si c’est votre première installation, choisissez le mode « full » : le fichier de configuration installe tous les modules optionnels.

---

Étape 2 : Enregistrer le service MCP

Si l’étape précédente n’a pas enregistré automatiquement le MCP, ajoutez-le manuellement :

claude mcp add ruflo -- npx -y @claude-flow/cli@latest mcp start

Vérifiez que l’enregistrement est réussi :

claude mcp list
# Attendu : sortie du type
# Name    Command                          Args  Status
# ruflo   npx -y @claude-flow/cli@latest  mcp  enabled

---

Étape 3 : Initialiser le premier Swarm (hierarchical + 5 agents)

npx ruflo swarm init --topology hierarchical --max-agents 8
npx ruflo agent spawn --type architect --name arch-1
npx ruflo agent spawn --type coder --name coder-1
npx ruflo agent spawn --type coder --name coder-2
npx ruflo agent spawn --type tester --name tester-1
npx ruflo agent spawn --type reviewer --name reviewer-1

---

Étape 4 : Faire communiquer les Agents via SendMessage

C’est l’une des conceptions les plus centrales de Ruflo : les Agents nommés communiquent en temps réel via SendMessage, sans polling ni partage d’un pool de mémoire :

// Dans l’outil Task de Claude Code :
Task({
  prompt: "Concevoir une solution pour une REST API. Une fois terminée, envoyer un SendMessage à 'coder-1' avec la proposition.",
  subagent_type: "system-architect",
  name: "arch-1",
  run_in_background: true
})

Task({
  prompt: "Attendre le design envoyé par arch-1. Une fois implémenté, envoyer un SendMessage à 'tester-1' pour lui rapporter le chemin du code.",
  subagent_type: "coder",
  name: "coder-1",
  run_in_background: true
})

Task({
  prompt: "Attendre le code envoyé par coder-1. Écrire des tests d’intégration. Une fois terminé, envoyer un SendMessage à 'reviewer-1' avec le résultat.",
  subagent_type: "tester",
  name: "tester-1",
  run_in_background: true
})

// Démarrer le pipeline — envoyer un message au premier Agent
SendMessage({
  to: "arch-1",
  summary: "Démarrer la conception de l’API",
  message: "Concevoir un ensemble de CRUD REST API pour la gestion des utilisateurs (ajout/suppression/modification/liste). Une fois la conception prête, l’envoyer à coder-1."
})

Flux du pipeline : arch-1 → coder-1 → tester-1 → reviewer-1 ; chaque Agent sait à qui passer la suite.

---

Étape 5 : Stocker la première mémoire (AgentDB + HNSW)

npx ruflo memory store \
  --key "pattern-auth-service" \
  --value "JWT auth : Bearer Token, express-jwt en middleware, refresh token stocké dans Redis, expiration 6 heures" \
  --namespace patterns

Le contenu stocké génère automatiquement des embeddings vectoriels, puis est enregistré dans AgentDB pour permettre des recherches sémantiques par la suite.

---

Étape 6 : Vérifier la mémoire via la recherche sémantique

npx ruflo memory search --query "authentication patterns" --namespace patterns

La sortie affichera les entrées correspondantes et un score de similarité (0-1, plus c’est élevé, plus c’est pertinent). Un score > 0.7 indique une correspondance très forte : vous pouvez l’utiliser directement.

---

Étape 7 : Démarrer le Daemon en arrière-plan + lancer un diagnostic santé

# Démarrer le processus de surveillance (12 workers automatiques commencent à tourner)
npx ruflo daemon start

# Diagnostic en un clic (version Node, API Key, connexion MCP, espace disque)
npx ruflo doctor --fix

doctor --fix répare automatiquement tout ce qu’il peut (par exemple des dépendances manquantes) et affiche un rapport complet de santé dans le terminal.

---

Étape 8 : Installer les plugins (selon vos besoins)

Les plugins s’installent très facilement : choisissez la fonctionnalité dont vous avez besoin.

# Ajouter le marketplace
/plugin marketplace add ruvnet/ruflo

# Installer le plugin de collaboration fédérée (communication multi-machines)
/plugin install ruflo-federation@ruflo

# Installer le plugin d’auto-apprentissage (mode neuronal SONA)
/plugin install ruflo-intelligence@ruflo

# Installer le plugin d’audit de sécurité
/plugin install ruflo-security-audit@ruflo

# Installer le plugin de suivi des coûts
/plugin install ruflo-cost-tracker@ruflo

Ou via CLI :

npx ruflo plugins install ruflo-federation
npx ruflo plugins list  # Voir tous les plugins disponibles

---

Étape 9 : Niveau avancé — appeler les capacités d’auto-évolution (SONA)

# Faire que SONA extrait des motifs et s’entraîne à partir des cas récents réussis
npx ruflo hooks post-task --task-id "abc-123" --success true --train-neural true

# Voir les motifs appris à l’instant
npx ruflo neural patterns

# Faire utiliser à la couche de routage le routage intelligent (89% de précision)
npx ruflo hooks route --task "Écrire un middleware d’API"

SONA exécute en arrière-plan un pipeline en 4 étapes : RETRIEVE (HNSW) → JUDGE (décision succès/échec) → DISTILL (distillation LoRA) → CONSOLIDATE (EWC++ pour éviter l’oubli catastrophique).

---

Résolution des problèmes fréquents

1. Échec de connexion MCP : dans claude mcp list, Ruflo apparaît en disabled

En général, c’est un souci de version Node ou un port déjà utilisé :

# Vérifier la version de Node
node -v  # doit être ≥20.0.0

# Redémarrer manuellement le service MCP
claude mcp remove ruflo
claude mcp add ruflo -- npx -y @claude-flow/cli@latest mcp start

# Vérifier l’occupation du port
lsof -i :3000  # macOS
netstat -tlnp | grep 3000  # Linux

---

2. Clé API non configurée : erreur ANTHROPIC_API_KEY is not set

Ruflo nécessite au moins une clé API d’un fournisseur de LLM :

# Paramétrage temporaire (valide pour la session courante)
export ANTHROPIC_API_KEY=sk-ant-xxxx

# Écriture permanente dans ~/.bashrc ou ~/.zshrc
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxx' >> ~/.zshrc

# Ou via un fichier de configuration (init --wizard vous guide pour écrire .env)
# Support de plusieurs providers : Claude / GPT / Gemini / Ollama
npx ruflo providers add anthropic --key sk-ant-xxxx
npx ruflo providers test anthropic  # Tester la connexion

---

3. Version Node insuffisante : ruflo: requires Node.js >=20.0.0

# Méthode 1 : utiliser nvm pour mettre à niveau
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 20
nvm use 20

# Méthode 2 : sur Windows, utiliser nvm-windows
# Télécharger : https://github.com/coreybutler/nvm-windows/releases
nvm install 20
nvm use 20

# Vérification
node -v  # doit afficher v20.x.x

---

4. memory search ne renvoie aucun résultat

Possible causes : espace de nom (namespace) mal orthographié, ou mémoire pas encore stockée :

# Afficher tous les namespaces
npx ruflo memory list --namespace

# Lister toutes les clés dans patterns
npx ruflo memory list --namespace patterns

# Récupérer une clé connue directement
npx ruflo memory retrieve --key "pattern-auth-service"

# Si la base est vide, essayez d’abord d’en stocker une entrée
npx ruflo memory store --key "test-entry" --value "hello world" --namespace patterns
npx ruflo memory search --query "test" --namespace patterns

---

5. Après démarrage du swarm, tous les Agents sont en idle

Cela signifie que la tâche n’a pas encore été transmise. Vérifiez ces points :

# Voir tous les états des Agents
npx ruflo agent list

# Vérifier si le swarm a bien été initialisé
npx ruflo swarm status

# Si vous lancez via l’outil Task de Claude Code, confirmez que vous avez envoyé le message de démarrage :
# SendMessage({ to: "arch-1", message: "Commencer" })
# Sans SendMessage, le premier Agent ne se lancera pas automatiquement

---

6. ruflo doctor signale MongoDB not running

Lors d’un lancement via Docker Compose (ruflo/src/ruvocal/), MongoDB est nécessaire :

# Méthode 1 : démarrer toutes les dépendances via Docker
cd ruflo/src/ruvocal
docker compose up -d

# Méthode 2 : mode monomachine intégré à Ruflo (sans MongoDB)
npx ruflo start --mode standalone
# Le mode standalone remplace MongoDB par sql.js (WASM) et fonctionne entièrement hors ligne

---

Pour aller plus loin / Pistes avancées

1. Agent Federation — collaboration zero-trust multi-machines

L’une des fonctionnalités les plus impressionnantes. Faites collaborer des Agents sur des machines différentes : les PII sont filtrées automatiquement avant l’envoi :

npx ruflo federation init
npx ruflo federation join wss://other-team.example.com:8443
npx ruflo federation send --to team-b --type task-request --message "Analyser les motifs de transactions"

Détails d’architecture : chaque message sortant passe par une détection PII en 14 types → politique à 4 niveaux (BLOCK / REDACT / HASH / PASS) → validation d’identité par mTLS + signature ed25519. Les comportements malveillants déclenchent automatiquement une baisse de confiance : aucune intervention manuelle n’est nécessaire.

2. Principe de recherche vectorielle RuVector HNSW

Ce n’est pas un simple matching par mots-clés : le texte est encodé en un vecteur de 384 dimensions. Dans l’espace vectoriel, HNSW (Hierarchical Navigable Small World) cherche les plus proches voisins. À chaque memory store, les embeddings sont générés automatiquement ; à chaque memory search, les résultats sont triés par similarité cosinus.

3. Mémo rapide de l’écosystème des 32 plugins

4. Expérience en ligne (sans installation)

• Interface de chat multi-modèles : https://flo.ruv.io/ — prend en charge Qwen 3.6 Max / Claude Sonnet / Gemini 2.5 Pro, appels MCP parallèles en ligne
• Interface de planification d’objectifs : https://goal.ruv.io/ — transforme votre phrase “faire tourner la refonte d’Auth et écrire des tests” en un chemin GOAP A*
• Tableau de bord Live des Agents : https://goal.ruv.io/agents — visualisez en temps réel l’état de chaque Agent, les namespaces de mémoire et le budget tokens

5. Index de la documentation officielle

6. Communauté Discord

Des questions ou envie de partager les Skills que vous avez créées ? RuvNet maintient une communauté active dans Agentics Foundation Discord :

https://discord.com/invite/dfxmpwkG2D

Vous y trouverez de nombreuses compétences $skill-name créées par des utilisateurs, directement réutilisables.