Ruflo setup + an AI agent team for every project

Ruflo is built by Reuven Cohen (rUv) and started as Claude Flow in June 2025. It is MIT licensed and had 81,104 stars on GitHub on 7 November 2026. The README's downloads badge counts 97,022,120 npm download events.

One harness. A separate team, memory and budget for every project.

Whether you build your own product, your team's tools or client projects, the hard part is the same: keeping each project's context, decisions and spend apart while you work on several at once. Ruflo gives each project folder its own agent setup, so that separation happens by default.

Read this guide: https://codewithnishant.dev/free/ruflo-agent-team-per-project/ and the official Ruflo README at https://github.com/ruvnet/ruflo. Help me set up Ruflo for one project of mine. First check my Claude Code version (the plugin path needs 2.1.287 or later) and that Node.js is installed for npx. Tell me what npx ruflo@latest init wizard will write into this project folder before running it, and wait for my OK. Install only from the official ruvnet/ruflo sources. Then run one read-only review of this project using Ruflo: summarize its purpose and how to run its tests, propose three independent review tasks, and do not edit files, install dependencies, publish or deploy. Show me what the session cost if the cost tracker is available. Tell me what is not working instead of guessing.

01. What Ruflo is

The README calls it "an agent meta-harness for Claude Code and Codex": the model writes, and the harness gives it tools, memory, loops and controls so it can actually work.

On the 250% number from the reel: Ruflo's user guide says smart routing "can extend your Claude Code usage by 250%". That is the maker's claim, not an independent test, and the README does not repeat it. Ruflo's own explainer adds that more agents are not automatically cheaper. Measure your own numbers.

02. Before you install

• Claude Code 2.1.287 or later for the plugin path. Check with claude --version.
• Node.js for the npx ruflo commands.
• Pick the right path. The README has two with very different reach: Claude Code plugins (slash commands, no files in your workspace, no hooks) or the CLI init (the full loop with hooks, MCP server and daemon, and files written into your project).
• Official sources only: the ruvnet/ruflo repository and the ruflo npm package.

The README says mods run with your account's permissions and are not sandboxed. Read the code before installing them, and start on a project without secrets.

03. Install Ruflo

Pick one path per project

Which path should you pick?

• Path A if you only want to look around: slash commands and the cockpit, nothing written into your project, no hooks.
• Path B if you want the full setup the reel talks about: agents, hooks, shared memory and the MCP server in each project.
• Both can be used. Many people try A first, then run B inside the one project they care about.

Path A: Claude Code plugins (light)

From the README's Get started section, run these inside Claude Code:

/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-console@ruflo
/plugin install ruflo-mods@ruflo
/reload-plugins
/ruflo

Core gives the foundation tools and registers the MCP server, Console opens the agent cockpit, and Mods add routing and policy checks inside Claude Code. The README says this path adds no files to your workspace and installs no hooks.

Path B: the full setup (CLI init)

Run this inside your project folder:

npx ruflo@latest init wizard

The README describes this as the full loop: 98 agents, 60+ commands, 30 skills, the MCP server, hooks and a background daemon. It writes .claude/, .claude-flow/, CLAUDE.md, helpers and settings into the folder. After init, the README says you just use Claude Code normally and the hooks route tasks and coordinate agents in the background.

Using Codex instead?

Run the same npx ruflo@latest init wizard in your project, then connect Codex to the Ruflo MCP server with command npx and arguments ["-y", "ruflo@latest", "mcp", "start"]. The equivalent server command is:

npx -y ruflo@latest mcp start

The console and mods are Claude Code integrations. I found no line in the README saying Codex gets the hooks, so treat the Codex route as the MCP server and agents only, and check the README for anything newer.

Open the cockpit

Run /ruflo in Claude Code, or npx ruflo tui in a plain terminal. The console tracks workflows, agents, models, tokens and cost. Its Claude control setting starts at read + ask; raise it only when you trust the setup.

04. One agent team per project

This is how I would set it up, built from the README's install table. Because the CLI init writes its files into the folder you run it in, each project folder carries its own setup and its own local .claude-flow/ data.

1. One folder per project. Your product, a team tool, each client: separate folders.
2. Run the init inside each folder with npx ruflo@latest init wizard. Do not share one setup across unrelated projects.
3. Write the project brief into that folder's CLAUDE.md: what the project is, the stack, what is in and out of scope, what the agents must never touch.
4. Start every session from that folder, so the swarm, memory and decisions stay with that project.
5. Start small. The explainer's rule: one coordinator, a few genuinely independent tasks, a fixed budget and a clear finish line.

Keep separate projects in separate folders. That is what keeps one project's memory and decisions out of another's work.

An example layout

This is a made-up example, not one of my setups. Say you run three things at once: your own app, a tool for your team and a client website. Keep them like this:

• ~/work/my-app: its own init, its own CLAUDE.md brief, its own cost report
• ~/work/team-tool: same steps, different brief, different rules
• ~/work/client-site: same steps, plus a line in the brief that client credentials are off limits

The folder names do not matter. What matters is that you never start a session for one project from another project's folder.

Check the separation yourself

The README says init adds memory to the project and writes .claude-flow/ into the folder. It does not spell out every place data can land, so do not take the separation on trust. After your second project is set up, do this once:

1. In project one, ask the agents to remember one made-up fact, like "the staging password format is purple-42".
2. Open project two from its own folder and ask what the staging password format is.
3. If project two answers, stop and read the memory settings before you put real client work through it. If it does not know, the separation works for that case.
4. Run /cost-report --period week in both folders and check the numbers differ and match what each project actually did.

Use a made-up fact, never a real secret, for this test. I have not run it, so treat the result as yours to confirm.

05. Track cost per project

The ruflo-cost-tracker plugin tracks token usage per agent, task and model and turns it into USD with current model pricing. Install it from the same marketplace, then run these from inside the project folder:

/plugin install ruflo-cost-tracker@ruflo
/cost-report --period week
/cost-budget-check --period month
/cost-optimize

• Budgets with alerts: info at 50%, warning at 75%, critical at 90% and a hard stop at 100%.
• Automatic capture: the plugin says /cost-track also runs at session end on its own.
• Compare routing: /cost-counterfactual compares your actual spend with always-Haiku, always-Sonnet and always-Opus.
• Across tools: /cost-ledger reads spend from local Claude Code, Codex and Grok logs.

The explainer's advice is the one I would follow: measure cost per accepted result, including retries and your own review time. A cheaper run that produces unusable work is not a saving. For client work, that per-project number is what helps you price the next job.

06. Ship more at once

Running several projects without mixing them

1. Plan in each project first. Ask the agents for a read-only plan before any edit, and approve one change at a time.
2. Split only independent work. The explainer shows parallel work can cut waiting time, but integration and duplicated context can raise the bill.
3. Keep evidence per project: the plan, the diff, the test results and the cost report. That is your handover record.
4. Check the cockpit, so you see which agents and models are running and what they cost.
5. Review before you merge. More agents means more output to read. The limit on how many projects you can run is how many you can review properly, not how many agents you can start.
6. Close each session with a cost check. Run /cost-report before you leave the folder, and write the number in your handover note.

New to client work? Start with my first client playbook. For giving Claude Code a memory without a full harness, see Claude Code memory setup.

07. Where it goes wrong

• Turning everything on at once. You do not need 406 MCP tools on day one. Start with one project and one read-only task.
• One setup for every project. Shared settings and memory mix decisions between projects. Init each folder separately.
• Plugin path, then expecting hooks. The plugin path installs no hooks and adds no files. Use the CLI init for the full loop.
• Trusting mods blindly. They run with your permissions and are not sandboxed. Read them first.
• Raising Claude control too fast. Keep the console on read + ask until you trust it. Network, spending and destructive actions still ask, even in auto.
• Expecting the 250% saving. It is the maker's figure. Track your own cost per finished result.
• Secrets and contracts. Keep keys and client credentials out of prompts, and check your contract before client code goes through any AI tool.

08. Copyable prompts

1. First read-only review of a project

Review this project using Ruflo where useful. First summarize its purpose and how to run its tests. Propose three independent review tasks. Keep the first pass read only. Do not install dependencies, edit files, publish or deploy. Return findings with file references, uncertainties and the exact checks you ran.

2. Write this project's brief into CLAUDE.md

Add a short project brief to this folder's CLAUDE.md: what the project is, the stack, what is in scope and out of scope, and the files and secrets agents must never touch. Show me the change before saving.

3. One scoped change with evidence

Implement only the change we agreed: [describe it]. Preserve unrelated work. Run the relevant tests. Show the diff, the test results and any remaining risks. Stop before committing or deploying.

4. This project's cost this week

/cost-report --period week

5. Handover note

Write a one-page handover note in plain words: what was built, how it was tested, what the review found and fixed, what this project cost in AI usage, and what to watch next. Do not claim anything that was not actually checked.

FAQ

What is Ruflo?

Ruflo is a free, open source agent harness by Reuven Cohen (rUv), originally called Claude Flow. It sits around Claude Code and Codex and adds 100+ specialized agents, coordinated swarms led by a queen agent, shared memory that carries across sessions, model routing and a console that shows agents, models, tokens and cost.

Is Ruflo free?

Yes. The repository is MIT licensed. You still pay for your own Claude Code plan, Codex plan or API use.

How do I install Ruflo in Claude Code?

For the light plugin path, run /plugin marketplace add ruvnet/ruflo inside Claude Code, then /plugin install ruflo-core@ruflo, ruflo-console@ruflo and ruflo-mods@ruflo, then /reload-plugins and /ruflo. It needs Claude Code 2.1.287 or later. For the full setup with hooks, the MCP server and the background daemon, run npx ruflo@latest init wizard in your project folder.

Does Ruflo work with Codex?

Yes, through its MCP server. Run npx ruflo@latest init wizard in your project and connect Codex to the server with the command npx and the arguments -y, ruflo@latest, mcp, start. The console and mods are Claude Code integrations, and I found no README line saying Codex gets the hooks, so treat Codex as the MCP server and agents only.

How do I give each project its own agent team?

Run the init inside each project folder. It writes its files, including CLAUDE.md, .claude/ and .claude-flow/, into the folder you run it in, so each project carries its own setup and its own local data. Then start the swarm for that project from inside that folder.

Can Ruflo really extend my Claude Code usage by 250 percent?

That number comes from Ruflo's own user guide, which says smart routing can extend Claude Code usage by 250 percent by skipping the model for simple edits and sending medium tasks to cheaper models. It is the maker's claim, not an independent test. Ruflo's own explainer also says more agents are not automatically cheaper, so measure your own cost per finished result.

Is it safe to install Ruflo?

Ruflo runs hooks, a daemon and mods with your account's permissions, and the README says mods are not sandboxed, so read the code before installing. Use only the official ruvnet/ruflo repository and the ruflo npm package, start on a small project without secrets and keep the console's Claude control on read + ask until you trust it.

What I checked, and what I did not

On 6 and 7 November 2026 I read the official README, the user guide, the explainer and the cost tracker plugin's README, and checked the repo on the GitHub API: 81,104 stars, 9,543 forks, MIT, latest release v3.72.2 from 6 November 2026. Every command and number above comes from those pages. The per-project setup is my way of using the maker's install, not a feature name of Ruflo. I did not install or run Ruflo myself, so expect to debug, and check the README again before you install because it changes almost daily.

One folder, one team, one memory, one budget. Then run as many projects as you can review.