Ruflo-Einstieg: Eine Multi-Agenten-Koordinations-Engine, die sich selbst weiterentwickelt

Projektüberblick

Ruflo ist eine Multi-Agenten-Orchestrierungsschicht für Claude Code. In einem Satz: Ruflo macht aus Claude Code vom „Chat-Assistenten“ ein „KI-Team, das kooperieren kann, sich merken kann und sich selbst weiterentwickelt“.

Ruflo hieß ursprünglich Claude Flow und wurde von RuvNet entwickelt (der Gründer hat einen Rust-Hintergrund; der Name setzt sich aus Ruv + Flow-Bildsprache zusammen). Der darunterliegende WASM-Kern, der in Rust geschrieben ist, übernimmt den Strategielayer: Strategie-Engine, Vektor-Einbettungen und ein Beweissystem – für hohe Performance.

Die neueste stabile Version [email protected] ist bereits ein vollständiges Enterprise-Produkt:

• 300+ MCP-Tools, die direkt in Claude Code eingespeist werden
• 60+ professionelle Agent-Rollen (coder, tester, architect, security-architect …)
• Lernfähiges Speichergedächtnis: AgentDB + HNSW-Vektorindex; Suche ist 150× bis 12.500× schneller als brutales Durchsuchen
• Föderierte Zusammenarbeit über Maschinen hinweg: Agent Federation – Zero-Trust-Kommunikation auf Basis von mTLS + ed25519
• Fähigkeit zur Selbstweiterentwicklung: SONA-Neural-Lernmodul – extrahiert Muster aus historischen Verläufen und optimiert kontinuierlich
• 32 Plugins für Sicherheit, Kosten-Tracking, Browser-Automatisierung, GitHub-Integration usw.

Spannend ist die Designphilosophie: Nachdem du es installiert hast, musst du keine 300 MCP-Tools lernen. Die Hooks-Routing-Schicht verteilt Aufgaben automatisch an den passenden Agent. Du schreibst weiter Code – Ruflo koordiniert im Hintergrund alles.

Schwierigkeitsgrad / Dauer / Nutzen

• Schwierigkeitsgrad: ★★☆☆☆ (läuft nach 5 Minuten Installation)
• Dauer: ca. 20 Minuten
• Nutzen: Swarm-Topologie und Lebenszyklus-Management beherrschen, HNSW-Vektor-Gedächtnisprinzip verstehen, lernen, wie Agenten über SendMessage miteinander kommunizieren

Zielgruppe

• Entwickler mit 1–5 Jahren Erfahrung
• Wer möchte KI von „Chat-Tool“ zu „Arbeitsteam“ machen?
• Solo-Entwickler oder kleine Teams, die Claude Code bereits nutzen oder dafür planen

Zentrale Abhängigkeiten & Umgebung

Vollständiger Projekt-Structure-Tree

 Ruflo/
├── bin/
│   ├── cli.js              # CLI-Einstieg (ruflo-Befehl)
│   └── mcp-server.js       # MCP-Server
│
├── v3/@claude-flow/        # Core-Modulpaket
│   ├── cli/                # 26 Top-Level-Kommandos (140+ Unterkommandos)
│   ├── memory/             # AgentDB + HNSW-Vektorsuche
│   ├── swarm/              # einheitlicher Koordinator (15-Agent hierarchical mesh)
│   ├── security/           # CVE-Fixes, Input-Validierung, Pfadsicherheit
│   ├── neural/             # SONA-Selbstlernmodul
│   ├── hooks/              # 17 Hooks + 12 Hintergrund-Worker
│   ├── guidance/           # Governance-Kontrollfläche (compile/enforce/prove/evolve)
│   └── shared/             # Typen, Events, zentrale Interfaces
│
├── plugins/                # 32 offizielle Plugins
│   ├── ruflo-core/         # Basis (Server, Health-Checks, Plugin-Discovery)
│   ├── ruflo-swarm/        # Koordination für Multi-Agent-Teams
│   ├── ruflo-federation/   # sichere Zusammenarbeit über Maschinen
│   ├── ruflo-agentdb/      # Vektor-Datenbankgedächtnis
│   ├── ruflo-intelligence/ # selbstlernende neuronale Muster
│   └── ...                 # die restlichen 27 Plugins
│
├── .claude/                # Claude Code-Konfiguration (MCP-Server, settings.json)
├── .agents/                # Agent-Fähigkeitsdefinitionen (Syntax: $skill-name)
└── mcp/                    # MCP-Tool-Definitionen (agent-tools.ts, memory-tools.ts usw.)

Schritt-für-Schritt Praxis

Schritt 1: Ein-Klick-Installation

Eine einzige Kommandozeile für die Initialisierung – inklusive geführtem Konfigurationsassistent:

npx ruflo@latest init --wizard

Dieser Befehl führt der Reihe nach aus:

1. Erzeugt im aktuellen Verzeichnis CLAUDE.md und schreibt Hooks-Routing-Regeln hinein
2. Registriert den MCP-Server in der Claude-Code-Konfiguration
3. Schreibt unter .claude-flow/ die Standardkonfiguration und eine Memory-Seed-Datei

Wenn du zum ersten Mal installierst, wähle „full“, um die Konfigurationsdatei mit allen optionalen Modulen zu installieren.

---

Schritt 2: MCP-Dienst registrieren

Wenn der vorherige Schritt MCP nicht automatisch registriert hat, ergänze es manuell:

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

Prüfen, ob es erfolgreich registriert wurde:

claude mcp list
# Erwartete Ausgabe ähnlich wie:
# Name    Command                          Args  Status
# ruflo   npx -y @claude-flow/cli@latest  mcp  enabled

---

Schritt 3: Initialisiere den ersten Swarm (hierarchical + 5 Agenten)

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

---

Schritt 4: Agenten sollen per SendMessage miteinander kommunizieren

Das ist das Kern-Design von Ruflo: Benannte Agenten kommunizieren in Echtzeit per SendMessage – ohne Polling oder einen gemeinsamen Memory-Pool:

// In der Task-Tool-Umgebung von Claude Code verwenden:
Task({
  prompt: "Entwirf eine REST-API-Lösung. Sende danach mit SendMessage an 'coder-1' und gib ihm die Lösung weiter.",
  subagent_type: "system-architect",
  name: "arch-1",
  run_in_background: true
})

Task({
  prompt: "Warte auf das Design von arch-1. Wenn die Umsetzung erledigt ist, sende mit SendMessage an 'tester-1' und melde den Codepfad.",
  subagent_type: "coder",
  name: "coder-1",
  run_in_background: true
})

Task({
  prompt: "Warte auf den Code von coder-1. Schreibe Integrationstests. Danach sende mit SendMessage an 'reviewer-1' und melde das Ergebnis.",
  subagent_type: "tester",
  name: "tester-1",
  run_in_background: true
})

// Pipeline starten – Nachricht an den ersten Agent
SendMessage({
  to: "arch-1",
  summary: "API-Design starten",
  message: "Entwirf eine CRUD-REST-API zur Verwaltung von Benutzern inklusive Erstellen, Ändern, Löschen und Abfragen. Wenn das Design fertig ist, sende es an coder-1."
})

Flussrichtung der Pipeline: arch-1 → coder-1 → tester-1 → reviewer-1 – jeder Agent weiß, an wen er als Nächstes senden muss.

---

Schritt 5: Die erste Erinnerung speichern (AgentDB + HNSW)

npx ruflo memory store \
  --key "pattern-auth-service" \
  --value "JWT-Authentifizierung: Bearer Token, express-jwt als Middleware, Refresh Token in Redis speichern, 6 Stunden Ablaufzeit" \
  --namespace patterns

Der gespeicherte Inhalt erzeugt automatisch Vektor-Einbettungen und wird in AgentDB für spätere semantische Suche verfügbar gemacht.

---

Schritt 6: Semantische Suche zur Verifikation

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

Die Ausgabe zeigt passende Einträge und Ähnlichkeitsscores (0–1; je höher, desto passender). Ein Score > 0,7 bedeutet starke Übereinstimmung – dann kann man ihn direkt verwenden.

---

Schritt 7: Hintergrund-Daemon starten + Health-Check ausführen

# Hintergrunddienst starten (12 automatische Worker starten)
npx ruflo daemon start

# Ein-Klick-Diagnose (Node-Version, API-Key, MCP-Verbindung, Plattenspeicher)
npx ruflo doctor --fix

doctor --fix behebt automatisch Probleme, die es beheben kann (z. B. fehlende Abhängigkeiten) und gibt anschließend einen vollständigen Health-Report im Terminal aus.

---

Schritt 8: Plugins installieren (nach Bedarf)

Plugins sind sehr einfach zu installieren – wähle die Funktionen, die du brauchst:

# Plugin-Marktplatz hinzufügen
/plugin marketplace add ruvnet/ruflo

# Föderations-Plugin installieren (Agent-Kommunikation über Maschinen)
/plugin install ruflo-federation@ruflo

# Selbstlern-Plugin installieren (SONA-Neural-Pattern)
/plugin install ruflo-intelligence@ruflo

# Sicherheits-Audit-Plugin installieren
/plugin install ruflo-security-audit@ruflo

# Kosten-Tracking-Plugin installieren
/plugin install ruflo-cost-tracker@ruflo

Oder per CLI:

npx ruflo plugins install ruflo-federation
npx ruflo plugins list  # Alle verfügbaren Plugins anzeigen

---

Schritt 9: Fortgeschritten – Selbstweiterentwicklung (SONA) aufrufen

# SONA aus den letzten erfolgreichen Beispielen Muster extrahieren lassen und trainieren
npx ruflo hooks post-task --task-id "abc-123" --success true --train-neural true

# Aktuell gelernte Muster ansehen
npx ruflo neural patterns

# Dem Routing-Layer intelligente Routen nutzen lassen (89% Genauigkeit)
npx ruflo hooks route --task "Schreibe einen API-Middleware"

SONA läuft im Hintergrund in einem 4-Stufen-Pipeline: RETRIEVE (HNSW) → JUDGE (Erfolgs-/Fehlurteil) → DISTILL (LoRA-Destillation) → CONSOLIDATE (EWC++ gegen katastrophales Vergessen).

---

Häufige Probleme beheben

1. MCP-Verbindung fehlgeschlagen: In claude mcp list zeigt ruflo disabled

Meist liegt es an einer Node-Version oder daran, dass der Port belegt ist:

# Node-Version prüfen
node -v  # Muss ≥20.0.0 sein

# MCP-Dienst manuell neu starten
claude mcp remove ruflo
claude mcp add ruflo -- npx -y @claude-flow/cli@latest mcp start

# Portbelegung prüfen
lsof -i :3000  # macOS
netstat -tlnp | grep 3000  # Linux

---

2. API Key nicht konfiguriert: Fehlermeldung ANTHROPIC_API_KEY is not set

Ruflo benötigt mindestens einen API-Key eines LLM-Anbieters:

# Temporär setzen (gilt nur für die aktuelle Session)
export ANTHROPIC_API_KEY=sk-ant-xxxx

# Dauerhaft in ~/.bashrc oder ~/.zshrc eintragen
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxx' >> ~/.zshrc

# Oder über Konfigurationsdatei (init --wizard führt dich beim Schreiben von .env)
# Unterstützt Claude / GPT / Gemini / Ollama für mehrere Provider
npx ruflo providers add anthropic --key sk-ant-xxxx
npx ruflo providers test anthropic  # Verbindung testen

---

3. Node-Version reicht nicht: ruflo: requires Node.js >=20.0.0

# Methode 1: Mit nvm aktualisieren
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 20
nvm use 20

# Methode 2: Unter Windows mit nvm-windows
# Installer herunterladen: https://github.com/coreybutler/nvm-windows/releases
nvm install 20
nvm use 20

# Verifizieren
node -v  # sollte v20.x.x anzeigen

---

4. memory search findet keine Ergebnisse

Mögliche Ursachen: Namespace falsch geschrieben oder die Erinnerung wurde noch nicht gespeichert:

# Alle aktuellen Namespaces anzeigen
npx ruflo memory list --namespace

# Alle Keys in patterns auflisten
npx ruflo memory list --namespace patterns

# Bekannten Key direkt abrufen
npx ruflo memory retrieve --key "pattern-auth-service"

# Wenn es eine leere Datenbasis ist, erst einen Eintrag speichern und testen
npx ruflo memory store --key "test-entry" --value "hello world" --namespace patterns
npx ruflo memory search --query "test" --namespace patterns

---

5. Nach dem Start des Swarms sind alle Agenten idle

Dann wurde die Aufgabe noch nicht verteilt. Prüfe Folgendes:

# Alle Agent-Status anzeigen
npx ruflo agent list

# Prüfen, ob der Swarm initialisiert ist
npx ruflo swarm status

# Wenn du den Swarm mit dem Claude-Code Task-Tool gestartet hast, bestätige, dass du die Startnachricht gesendet hast:
# SendMessage({ to: "arch-1", message: "Jetzt loslegen" })
# Ohne SendMessage startet der erste Agent nicht automatisch

---

6. ruflo doctor meldet MongoDB not running

Bei Start via Docker Compose (ruflo/src/ruvocal/) wird MongoDB benötigt:

# Methode 1: Mit Docker alle Abhängigkeiten starten
cd ruflo/src/ruvocal
docker compose up -d

# Methode 2: Mit dem eingebauten Single-Node-Modus von ruflo (kein MongoDB nötig)
npx ruflo start --mode standalone
# Im standalone-Modus ersetzt sql.js (WASM) MongoDB – vollständig offline nutzbar

---

Weiterführende Lektüre / Fortgeschrittene Richtungen

1. Agent Federation – Zero-Trust-Zusammenarbeit über Maschinen hinweg

Eines der coolsten Features. Lass Agenten auf verschiedenen Maschinen zusammenarbeiten; PII wird automatisch gefiltert, bevor es überhaupt gesendet wird:

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 "Transaktionsmuster analysieren"

Architektur-Details: Jede ausgehende Nachricht durchläuft 14 Typen von PII-Checks → BLOCK / REDACT / HASH / PASS als Vier-Stufen-Strategie → mTLS + ed25519 zur Signaturprüfung der Identität. Böswilliges Verhalten triggert automatisch ein Herabstufen des Vertrauens – ohne manuellen Eingriff.

2. RuVector HNSW – Prinzip der Vektorsuche

Es ist nicht nur ein simples Keyword-Matching: Texte werden in 384-dimensionalen Vektoren kodiert, und im Vektorraum findet HNSW (Hierarchical Navigable Small World) die nächsten Nachbarn. Jeder memory store erzeugt automatisch Einbettungen; jeder memory search sortiert Ergebnisse über die Kosinus-Ähnlichkeit.

3. Schnellübersicht über das 32-Plugins-Ökosystem

4. Online-Erlebnis (ohne Installation)

• Multi-Model Chat-UI: https://flo.ruv.io/ — unterstützt Qwen 3.6 Max / Claude Sonnet / Gemini 2.5 Pro und ruft MCP-Tools online parallel auf
• Zielplanungs-UI: https://goal.ruv.io/ — zerlegt „Bringe das Auth-Refactoring zum Laufen und schreibe Tests“ in einen GOAP-A*-Pfad
• Live Agent-Dashboard: https://goal.ruv.io/agents — zeigt in Echtzeit den Status jedes Agenten, Memory-Namespaces und Token-Budget

5. Index der offiziellen Dokumente

6. Discord-Community

Hast du Probleme oder möchtest du Skills teilen, die du gebaut hast? RuvNet pflegt im Agentics-Foundation-Discord eine aktive Community:

https://discord.com/invite/dfxmpwkG2D

Dort gibt es viele von Nutzern selbst erstellte $skill-name-Skills, die du direkt übernehmen kannst.