Ruflo - User and Developer Guide
Ruflo is a multi-agent orchestration layer that sits on top of tools like Claude Code and Codex. It adds swarms, shared memory, hooks, plugins, security controls, and optional cross-machine federation. This guide explains what Ruflo is good at, where it is overkill, and how to adopt it without drowning in its surface area.
1. What is Ruflo?​
Ruflo is the project formerly known as Claude Flow. The core idea is simple:
- your coding agent keeps doing the actual coding work
- Ruflo coordinates additional agents, memory, routing, and automation around that work
- the orchestration can be reached through CLI commands, an MCP server, plugins, hooks, and background workers
The official README describes it as a harness for Claude Code and Codex, with 100+ specialized agents, plugin-based capabilities, self-learning memory, and zero-trust federation across machines and teams.
The right mental model​
| Layer | Role |
|---|---|
| Claude Code / Codex | The worker that reads files, edits code, runs commands, and solves tasks |
| Ruflo | The orchestrator that routes work, remembers patterns, coordinates swarms, and adds automation |
| LLM providers | Claude, GPT, Gemini, Ollama, and other model backends |
If you expect Ruflo itself to build your feature end to end, you will misunderstand the product. Even Ruflo's own AGENTS.md makes this explicit: the coding agent executes the work, Ruflo tracks and coordinates it.
2. Why people use Ruflo​
Ruflo is attractive because it tries to turn a single coding agent into a system.
The main advantages​
| Advantage | Why it matters |
|---|---|
| Multi-agent orchestration | Lets you split work into planner, coder, reviewer, tester, security, docs, and other roles |
| Persistent memory | Stores patterns and prior results so future runs can reuse what worked |
| Plugin marketplace | You can add focused capabilities like swarm coordination, RAG memory, test generation, docs, security, or observability |
| Hooks and background workers | Automation can happen before, during, and after your normal coding loop |
| MCP server | Exposes Ruflo capabilities to agent clients through the standard tool protocol |
| Security layer | The project documents input validation, path traversal prevention, command injection protection, and vulnerability reporting workflows |
| Federation | Teams can connect agent installations across machines without turning everything into one flat shared state |
What stands out compared with ordinary coding agents​
Most coding agents are optimized for one agent, one session, one repo. Ruflo pushes toward:
- team workflows
- repeatable orchestration
- reusable memory
- long-running automation
- specialized plugins instead of one giant monolith
That is the real value proposition. Ruflo is less "a better chat" and more "an operating layer for agentic software work."
3. Where Ruflo fits well, and where it does not​
Ruflo is a good fit when...​
- you already use Claude Code or Codex and want more structure around repeated work
- you want planner + coder + reviewer + tester style coordination
- your team wants shared conventions, hooks, memory, and automation
- you care about MCP-based extensibility
- you want to experiment with plugins rather than build every workflow yourself
- you are comfortable with a system that has many moving parts
Ruflo is a poor fit when...​
- you only want a fast, simple single-agent CLI
- you are still learning the basics of Claude Code or Codex
- you do not want extra folders, hooks, daemons, or orchestration state in your workspace
- you want minimal operational complexity
- you mainly need editor inline completion rather than workflow orchestration
If Claude Code or Codex alone already feels "too much", Ruflo is probably too much right now. If those tools feel too isolated or repetitive, Ruflo becomes interesting.
4. The most important decision: plugin path vs. full install​
Ruflo has two very different onboarding paths.
| Path | What you get | Best for | Main trade-off |
|---|---|---|---|
| Plugin install | Slash commands, some skills, agent definitions | Trying features with low commitment | No full MCP loop, no full hook-based orchestration |
npx ruflo init | Full workspace setup, MCP server, hooks, daemon, helpers, settings | Real adoption and production-style use | More files, more complexity, more behavior changes |
Start with the plugin path if...​
- you want to inspect the ecosystem first
- you are not ready to modify a repo
- you only need a narrow feature set
Start with init wizard if...​
- you actually want the orchestration model Ruflo advertises
- you want memory, hooks, background workers, and full MCP access
- you are evaluating Ruflo seriously as part of your workflow
Recommended first commands​
# Cross-platform guided setup
npx ruflo@latest init wizard
# Add Ruflo as an MCP server in Claude Code
claude mcp add ruflo -- npx ruflo@latest mcp start
The repository package metadata currently still shows some of the old Claude Flow naming in places. Treat the rebrand as real, but expect naming overlap in commands, docs, dependencies, or package internals while the ecosystem catches up.
5. How you should use Ruflo​
The best way to adopt Ruflo is incrementally.
5.1 Solo developer path​
- Learn your base agent first: Claude Code or Codex.
- Try Ruflo in a throwaway repo with
npx ruflo@latest init wizard. - Use only core orchestration and memory for a week.
- Add plugins one by one instead of installing everything mentally at once.
- Keep a close eye on what hooks and background workers actually do.
Best early plugins​
| Plugin | Why start here |
|---|---|
ruflo-core | Base runtime, health checks, discovery |
ruflo-swarm | The core coordination idea |
ruflo-rag-memory | Useful if you want memory to become practical rather than theoretical |
ruflo-docs | Helpful for documentation-heavy repositories |
ruflo-testgen | Good when you want missing-test assistance |
ruflo-metaharness | Useful once you want to audit the agent setup itself |
5.2 Team path​
Ruflo becomes more compelling when a team wants:
- standard hooks
- consistent agent roles
- shared operational patterns
- secure boundaries between installations
- auditability around agent behavior
For teams, the biggest value is not raw coding speed. It is workflow standardization.
5.3 Codex users: what to expect​
Ruflo publicly claims Codex support, and the repo includes Codex-facing references and package dependencies. Still, the onboarding and examples are currently more Claude-centric than Codex-centric.
That means:
- the orchestration ideas still apply to Codex
- MCP remains the main interoperability story
- but some public docs, examples, and plugin flows are written first for Claude Code users
That is not a deal-breaker, but it is worth knowing before you expect a perfectly symmetric experience.
6. Recommended adoption strategy​
If you want the highest signal with the lowest chaos, use this order:
Phase 1 - Evaluate the concept​
- run
npx ruflo@latest init wizardin a non-critical repo - confirm Node 20+ on your machine
- inspect which files Ruflo adds to the workspace
- run a few ordinary tasks and watch whether the hooks help or distract
Phase 2 - Add practical value​
- enable memory and swarm features
- try docs/test/security plugins based on a real project pain point
- decide whether the system is making results better or just more elaborate
Phase 3 - Operationalize​
- add observability and cost tracking
- introduce metaharness and security audit features
- document which plugins are allowed in your team and why
Phase 4 - Only then consider federation​
Federation is interesting, but it is not step one. Do not distribute a system across machines and trust boundaries before you trust it on one machine.
7. Developer guide​
If you want to build on Ruflo rather than only use it, focus on the extension points.
7.1 Understand the architecture first​
From the public docs and repo structure, the important pieces are:
| Area | What it appears to own |
|---|---|
docs/ | Large user guide, status, roadmap, validation, and operational material |
plugins/ | Feature-specific packages such as swarm, memory, docs, security, workflows, and observability |
.claude-plugin/ | Claude plugin packaging and marketplace metadata |
v3/ | Current package implementation split across CLI, shared logic, guidance, and related modules |
| MCP server | Tool interface for agent clients |
7.2 Start as a plugin consumer before becoming a plugin author​
Ruflo already ships a broad plugin catalog. Before writing your own plugin:
- identify whether an existing plugin is close enough
- test how hooks, commands, and memory interact
- map the operational cost of another plugin in your workflow
Only then does custom plugin work make sense.
7.3 Good plugin candidates​
Write or extend plugins when your team repeatedly needs:
- internal standards enforcement
- repo-specific review workflows
- custom architecture or ADR tooling
- company-specific connectors or MCP tools
- domain-specific automation that is too narrow for the upstream project
7.4 Design rules for extending Ruflo safely​
- keep plugins small and focused
- prefer observable behavior over magical behavior
- document side effects clearly
- avoid silent write actions
- treat hooks as production code, not as cute glue
- test failure modes, not just happy paths
7.5 Security matters more here than in ordinary CLI tools​
Because Ruflo is about orchestration, automation, and cross-tool execution, security hygiene matters a lot. The project's documented security posture includes:
- schema validation for public inputs
- protection against path traversal
- protection against command injection
- a defined vulnerability reporting process
If you extend Ruflo, keep your additions at least that strict.
8. Caveats you should know before committing​
Ruflo is impressive, but it is not a lightweight tool.
The main caveats​
| Caveat | Why it matters |
|---|---|
| Large surface area | It is easy to install more than you can realistically understand |
| Naming overlap | Repo, package, and docs still show both Ruflo and Claude Flow in places |
| Documentation scale | The project has a very large user guide and many moving parts, which raises onboarding cost |
| Claude-first ergonomics | Codex support exists, but many public examples are Claude-oriented |
| Operational complexity | Hooks, daemons, memory stores, plugins, and federation all increase the number of failure modes |
Ruflo can expose a lot of power quickly. That does not automatically mean every enabled capability belongs in your daily workflow.
9. So should you use Ruflo?​
Yes, if...​
- you want an orchestration layer, not just a coding chat
- you are serious about multi-agent workflows
- you want plugins, memory, and MCP-based extensibility
- you are willing to operate a more complex system
No, if...​
- you mainly want "one model, one task, one terminal"
- you do not want automation touching your workflow
- you are still choosing between Claude Code, Codex, Copilot, Cursor, or OpenCode at a basic level
My practical recommendation​
Use Ruflo as a second-layer tool.
- First choose your primary coding agent.
- Then decide whether you need orchestration badly enough to justify the overhead.
- If yes, start small with core + swarm + memory and grow from there.
That is the healthiest way to get Ruflo's strengths without importing all of its complexity at once.