Ruflo

1. What is Ruflo? (Ruflo GitHub explained)

Ruflo is a tool for software developers. It is not a chat app, it has no window to click around in, and on its own it does not write a single line of code. Ruflo is an add-on layer for Claude Code or Codex (two AI coding assistants that run in a terminal) that lets those assistants work as a team.

The author explains the idea this way: the AI model does the writing, while the "harness" (the framework wrapped around the model) supplies tools, memory and coordination. Ruflo is that harness. With the full install it adds about 100 specialized agents (the README says "100+" in one place and 98 in another) (an agent is an "AI worker" with one role, such as coding, testing or security review), lets them cooperate in groups, and keeps memory across sessions. The project used to be called Claude Flow, which is why you will still see claude-flow in some commands and folder names.

Ruflo is open source under the MIT license and free. It does, however, need a coding assistant underneath it, and that assistant usually costs money.

A good fit if:

• You already use Claude Code or Codex to build software.
• Your project is large enough that splitting work across several agents makes sense.
• You are comfortable typing commands and reading English output.

Not a good fit if:

• You have never programmed. Without a software project to work on, Ruflo has nothing to do.
• You want a free chatbot. Ruflo does not include any AI model.
• You installed Claude Code yesterday. Use plain Claude Code for a while first, then add Ruflo.

2. What do you need?

• A computer running Windows, macOS or Linux. Ruflo does not run on phones.
• Node.js 20 or newer, with npm 9 or newer. Node.js is software for running JavaScript-based tools; npm is the package installer that comes with it. Download: https://nodejs.org
• Claude Code, installed and signed in. The Ruflo documentation says it must be installed first. Claude Code is an Anthropic product and requires a paid subscription or a paid API key; see https://docs.anthropic.com/en/docs/claude-code
• Git, the source-control tool. Ruflo's health check looks for it. Download: https://git-scm.com/downloads
• Disk space: about 340 MB for the full install, about 45 MB for the minimal one.
• A project folder to try it on. The author recommends a small project that contains no passwords or secret keys.

The newest Ruflo release at the time of writing is v3.48.0, published on 28 September 2026.

3. How to install Ruflo, step by step

Ruflo has two quite different install paths. Pick just one; the author's guide warns that running two copies side by side confuses the assistant's tool discovery.

	Path A: plugin inside Claude Code	Path B: command-line install
What you get	Slash commands, a few skills and agent definitions	All of Ruflo: agents, commands, skills, MCP server, hooks
Files added to your project	None	.claude/, .claude-flow/, CLAUDE.md and some helpers
Choose it when	You want a light trial that leaves the project untouched	You want real use with everything the docs describe

Step 1: Check Node.js

node --version
npm --version

You are on track when: the first number is v20 or higher and the second is 9 or higher. If the command is not found or the number is lower, install the current version from https://nodejs.org and reopen your terminal.

Step 2: Install Claude Code (if you do not have it)

npm install -g @anthropic-ai/claude-code

Then type claude to start it and sign in as prompted.

You are on track when: typing claude opens the Claude Code interface.

Step 3 (Path A): Install the plugin inside Claude Code

These two commands are typed inside Claude Code, not in the ordinary terminal:

/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo

ruflo-core is enough to begin. Add other plugins only when you have a specific need, for example ruflo-swarm for coordinating a team of agents:

/plugin install ruflo-swarm@ruflo

You are on track when: Claude Code confirms the plugin was installed and new Ruflo commands show up when you type /.

Step 3 (Path B): Full command-line install

First use cd to move into your project folder. Then run the command below; it behaves the same on Windows (PowerShell or cmd), macOS and Linux:

npx ruflo@latest init wizard

The wizard asks a few questions and then writes the configuration. To skip the questions, use the quick version:

npx ruflo@latest init

On macOS, Linux or WSL there is also a one-line installer:

curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash

You are on track when: your project folder now contains a .claude/ folder, a .claude-flow/ folder and a CLAUDE.md file.

Note: If your project already has its own .claude/ folder or CLAUDE.md, back them up before running init.

Step 4: Run the health check

npx ruflo@latest doctor

This checks your Node.js, npm and Git versions, the config file, the memory store, the MCP server and free disk space.

You are on track when: you see the list of checks and a summary line with the number passed. For items that can be repaired automatically, also run:

npx ruflo@latest doctor --fix

4. First use

The most useful thing to know: after init, you simply use Claude Code as usual. The README says outright that you do not need to learn the hundreds of tools and dozens of commands; the hooks system routes tasks and coordinates agents in the background.

Try something safe, following the author's advice to start with inspection rather than changes:

1. Open a terminal in your project folder and type claude.
2. Paste a request like this:

Review this project, using Ruflo where it helps. First summarize what the project is for and how to run its tests. Propose three independent review tasks. Keep the first pass read-only: install nothing, edit no files, do not commit or deploy. Return findings with file references and anything you are unsure about.

3. Read the plan the assistant proposes. Only once it looks right, authorize one specific change with a clear stopping condition.

What the result looks like: a summary of the project plus a list of proposed tasks, with no files modified.

To see which agent types Ruflo provides:

npx ruflo@latest agent list

The author has written a 14-chapter beginner guide, available at https://github.com/ruvnet/ruflo/blob/main/docs/ruflo-explained.md

5. Common Ruflo install problems and fixes

Symptom	Cause	Fix
Windows reports 'bash' is not recognized	The one-line curl ... | bash installer needs a Linux-style shell	Use npx ruflo@latest init wizard instead. Both run the same setup
npx or node gives "command not found" / "not recognized"	Node.js is missing, or the terminal has not picked it up	Install Node.js from https://nodejs.org, then close and reopen the terminal
doctor flags Node.js	Node.js is older than version 20	Upgrade Node.js by hand. This is one of the checks doctor cannot fix for you
"permission denied" while installing on macOS / Linux	The npm cache folder is owned by another account	Run the ownership fix shown below the table
The MCP server will not start	Another process is already using its port	Find and stop that process, then run npx ruflo@latest mcp start. Sample commands are in the Troubleshooting section of the User Guide
Agents fail to spawn on a low-memory machine	Too many agents running at once	Lower the maximum with the environment variable shown below the table
The assistant sees duplicate Ruflo tools	You installed both the plugin and a direct MCP registration	Keep one connection path and remove the other

Fix npm ownership (macOS / Linux):

sudo chown -R $(whoami) ~/.npm

Lower the agent limit (macOS / Linux):

export CLAUDE_FLOW_MAX_AGENTS=5

Still stuck? See the User Guide at https://github.com/ruvnet/ruflo/blob/main/docs/USERGUIDE.md or ask in the Issues tracker the README points to: https://github.com/ruvnet/claude-flow/issues

6. Uninstalling / updating

Updating (Path B): run this inside your project folder.

npx ruflo@latest init upgrade

It refreshes the helper files and keeps your data. To also add skills, agents and commands introduced in newer versions:

npx ruflo@latest init upgrade --add-missing

Removing (Path B):

1. In the project folder, delete what init created: the .claude-flow/ folder, plus the .claude/ folder and CLAUDE.md file if Ruflo generated them. If you had those files before, just restore your backup.
2. If you installed Ruflo globally with npm install -g ruflo@latest, remove it with:

npm uninstall -g ruflo

3. If you registered the MCP server with claude mcp add claude-flow ..., remove it with:

claude mcp remove claude-flow

Removing (Path A): open Claude Code, type /plugin and uninstall the plugins whose names begin with ruflo- from the plugin manager. This path leaves no files in your project.

7. Frequently asked questions

Does it cost money? Ruflo itself is free and MIT licensed. What costs money is the assistant and AI model underneath. The author also points out that running agents in parallel can shorten the wait while increasing token usage, so it may cost more rather than less.

Do I need an internet connection? Yes, both to download the package through npx and for the assistant to reach the AI model. The documentation mentions running local models through Ollama with a separate plugin, but that is an advanced setup.

Is my data sent anywhere? The configuration files Ruflo creates live in your project folder, and its memory is a database stored on your own machine. However, as with any AI coding assistant, whatever you ask it to work on is still sent to the model provider you use. Linking agents across machines (federation) is optional and has to be switched on by you.

Can I use it without knowing how to program? Not really. Ruflo is only useful when you have a software project and can read and approve the changes agents propose.

Does it work with Codex instead of Claude Code? Yes. There is a dedicated init command for Codex, npx ruflo@latest init --codex. See the User Guide for details.