AI Guides › Step-by-step guides
By Nigel Guy · 5 min read
The usual mistake is installing the biggest multi-agent framework you can find and typing "build me an app". You get dozens of agents, a large token bill and a pile of code nobody has read. A swarm does not remove the thinking; it moves it into the brief you write before anything starts.
The rule: split the work into named roles with written boundaries first, start with two or three agents, and only add more when the previous run was reviewed and was good.
The tool in the source material was called claude-flow. According to its official GitHub repository it is now called Ruflo ("formerly Claude Flow"), MIT-licensed and maintained by ruvnet. The repository describes it as a harness around Claude Code that adds specialised agents, coordinated swarms, memory and hooks. It claims "100+" agents. We could not verify the "60 or more agents at once" figure you may have seen, and we could not verify any claim about how many agents run well in parallel. Treat both as marketing until you have measured them yourself.
What you need:
npx available. The README excerpt we checked did not state a minimum Node version, so check the repository if npx complains.Anthropic also ships its own subagents in Claude Code. Subagents are Markdown files in .claude/agents/ or ~/.claude/agents/, each with its own context window and optional tool and model restrictions. Try these first. Ruflo is worth adding only if they genuinely fall short.
The README describes two routes with, in its words, very different surface areas:
/plugin marketplace add ruvnet/ruflo, then install individual plugins.npx ruflo@latest init wizard, or npm install -g ruflo@latest.For a first trial, take the plugin route. Plugins run with your account permissions and are not sandboxed, so read what you install.
Avoid the one-line curl ... | bash script until you have read it. Windows users: the README says npx works in PowerShell or cmd, but curl-piping does not.
In your throwaway project, run npx ruflo@latest init wizard and read every prompt before accepting. Afterwards, look at what it added to the folder (settings, hooks, config files). The README says hooks then route tasks in the background, which means a tool is now acting on your behalf. Know which files changed.
The README gives this command, and note it still uses the old name:
claude mcp add claude-flow -- npx ruflo@latest mcp start
Then run /mcp in Claude Code to confirm the server is listed.
The source article also showed claude-flow start --agents 3 "Build me a CLI tool that counts words". We could not confirm that exact command in current documentation, so do not paste it. Run npx ruflo@latest --help and use the commands your installed version prints.
This is the named mechanism. A Role Sheet is a table with one row per agent: its job, the files it may touch, the files it must not touch, and what "done" looks like. Without it, agents overlap and overwrite each other.
| Agent | Job | May touch | Must not touch | Done when |
|---|---|---|---|---|
| Builder | Write the word-count function | src/ |
tests/ |
Function exists |
| Tester | Write tests from the brief | tests/ |
src/ |
Tests run |
| Reviewer | Read both, list problems | nothing (read only) | everything | List delivered |
Have Claude draft it, then edit it yourself:
You are a senior engineer planning a small multi-agent build.
Goal: [WHAT_YOU_WANT_BUILT]
Constraints: [LANGUAGE_AND_TOOLS], [FILES_OR_FOLDERS_OFF_LIMITS], [TIME_OR_TOKEN_BUDGET]
Produce a Role Sheet for no more than [NUMBER_OF_AGENTS] agents as a table:
agent, job, files it may touch, files it must not touch, definition of done.
Then give the order the agents should run in and which can run at the same time.
Rules: no two agents may edit the same file; one agent must be a read-only reviewer;
if the goal is too large for that many agents, say what you would cut instead of adding agents.
If any input above is missing, ask me before answering.
Before you reply, check that every file appears under at most one "may touch" cell.
Fill in the goal, tools, off-limits paths and the agent cap.
Start with the Role Sheet's three agents. Paste it into the task you give the tool.
Work from the attached Role Sheet exactly. Stay inside your "may touch" files.
Task: [ONE_SENTENCE_TASK]
Stop and report if you need to edit a file outside your list or if the sheet is ambiguous.
At the end, list files changed, commands run, and anything you did not finish.
Fill in a single concrete task.
git status and git diff. Every changed file should sit inside one agent's "may touch" list.