ruflo

Overview

Ruflo is an "agent meta-harness" for Claude Code and Codex. Its core idea is: Agent = Model + Harness. The model is responsible for generating content, while the Harness provides it with tools, memory, loops, sandboxes, and control capabilities so that it can truly perform work. Ruflo is this execution layer around Claude Code and Codex, providing over 100 specialized agents, collaborative swarms, self-learning memory, cross-machine federation communication, and enterprise security guardrails, so that agents can not only run, but also collaborate.

The project was formerly named Claude Flow and is now renamed Ruflo. "Ru" stands for the author rUv, and "flo" implies continuous work. It is powered underneath by a Rust-based AI engine, embeddings, memory, and a plugin system.

Main Capabilities

• Multi-agent swarms and autonomous workflows: Agents can self-organize into swarms, coordinate autonomous workflows, and build conversational AI systems.
• Adaptive memory and self-learning: Learn from every task and remember across sessions. Local vector retrieval and contrastive updates can run without using an LLM, but embeddings and a configured learning module are still required.
• Agent Federation: Described as "Slack for agents," it provides a shared workspace for agents across trust boundaries. Agents on different machines, in different organizations, or in different cloud regions can discover each other, verify identity, and collaborate. It is handled by @claude-flow/plugin-agent-federation, verified via mTLS + ed25519; PII is stripped before leaving a node, and all messages are auditable; untrusted agents participate with lower privileges (they can only see discovery information, not memory), and trust can be upgraded or immediately downgraded. Users do not need to configure handshakes or manage certificates; simply use federation init and federation join.
• Vector RAG integration: Supports vector retrieval and RAG-related capabilities.
• Integrations and tools: Native integration with Claude Code, Codex, Hermes, and various other MCP-supported tools.
• Security policies: Enterprise-grade security guardrails for network, spending, and destructive operations, even in automatic mode.Needs confirmation.

How to use

Getting started in Claude Code

Requires Claude Code 2.1.287 or later. Run inside Claude Code:

• Get the core tools, the visual console, and runtime mods.
• The core provides the base tools; the console opens the agent cockpit; mods add routing and policy enforcement inside Claude Code. Mods run with your account's permissions, so review their code before installing.

Install mods from the ruflo marketplace (requires Claude Code 2.1.287+):

• ruflo-console: console cockpit
• ruflo-mods: route prompts and enforce policies in-process
• ruflo-swarm: show swarms in the panel
• ruflo-ruos: add a ruOS status segment

After installing, open /plugin to confirm they appear in the active mods line. Inside the console, /ruflo market is the plugin directory, listing every ruflo plugin, mod, and skill along with their contents, and providing install, enable, disable, and update buttons (each action asks first).

Using Codex or other MCP tools

Use NPX for Ruflo project setup and connect the client to the Ruflo MCP server. Run the setup wizard in the project terminal.

For clients that support local stdio MCP servers, configure command as npx and args as ["-y", "ruflo@latest", "mcp", "start"]. The equivalent server command is the same. MCP exposes Ruflo tools to the client; the console and mods are Claude Code integrations, and hook support depends on the client.

Terminal UI (optional)

The console can also run standalone, without Claude Code: npx ruflo tui (add --plain to print a single frame for scripts). It shows Overview, Cost, Swarm, Events, and Missions, plus optional AI pages.

ruOS desktop (optional)

You can connect ruOS to ChatGPT or Claude via MCP.

Initialization

A single npx ruflo init gives Claude Code a "nervous system": agents self-organize into swarms, learn from every task, remember across sessions, and can securely communicate with agents on other machines via federation without leaking data. After initialization, there is no need to learn 314 MCP tools or 26 CLI commands; just use Claude Code normally, and the hooks system automatically routes tasks, learns successful patterns, and coordinates agents in the background.

Two installation paths

• Path A — Claude Code plugin (lightweight, slash commands only): Adds slash commands and agent definitions. ruflo-core registers its own MCP server on install, and its tools are invoked as mcp__plugin_ruflo-core_ruflo__* rather than bare names. Other plugins usually do not ship their own MCP server. If you need the full loop and CLI-track tool names, use Path B.
• Path B (CLI track): Provides the full loop and CLI tool names.

macOS / Linux / WSL / Git-Bash can use the curl ... | bash form; all platforms (including native Windows PowerShell / cmd) can use the npx ruflo@latest init wizard. Note for Windows users: curl ... | bash requires a POSIX shell (Git-Bash, WSL, MSYS), while the npx line runs natively in PowerShell and cmd. If you encounter a 'bash' is not recognized error, use the npx line instead.

Visual console

The console is the agent cockpit, tracking workflows, agents, models, tokens, and costs alongside Claude Code. You can inspect any run: open agent logs and results, search, classify failures, replay, and compare. Start with npx ruflo init, restart Claude Code, then use /ruflo.

Claude control

Via Settings → Claude control you can navigate and run console actions. Permission levels can be read, write, manage, or full, and approval can be ask or auto. The current default is read + ask. Operations above the permission level will be rejected; network, spending, and destructive operations require confirmation even under auto. You can view the live operation log or press Take back control to stop Claude's control.

Learning Mechanism

Useful trajectories and task feedback can influence future work. Results depend on the configured memory, learning components, and feedback quality. Related content includes RuVector training integration and trajectory contrastive learning.

Applicable Scenarios

• Developers who want to give Claude Code / Codex multi-agent collaboration and autonomous workflow capabilities.
• Teams that need cross-session memory, self-learning, and task cost tracking.
• Scenarios that require secure collaboration of agents across machines or organizations (federation).
• Users who want to inspect, debug, and replay agent runs with a visual console.
• Users who use an MCP-compatible client and want to connect to the Ruflo toolchain.

Limitations and Notes

• Starting in Claude Code requires Claude Code 2.1.287 or later.
• mods run with your account permissions and are not in a sandbox; review the code before installing.
• Although local vector retrieval and contrastive updates can work without relying on an LLM, they still require embeddings and a configured learning module.
• hooks support depends on the client; the console and mods are part of the Claude Code integration.
• The console animations and theme demos shown in the documentation use sample data or replayed rendered frames and do not represent completed swarm work or memory recall.
• Creating a mission does not mean the feature has been implemented.
• The federation's WireGuard mesh layer is optional (opt-in).
• Information about fees, pricing, etc. is not provided in the materials.