ruflo: Multi-Agent Orchestration for Claude in Production

@jetpippo called it right: single agents are hitting a ceiling. Ask one Claude session to plan an API, write the code, write the tests, and review its own work, and you get a session juggling four jobs badly instead of one job well. ruflo is built on a simple bet — split that work across specialized agents that run concurrently and share memory, instead of asking one context window to context-switch all day.

I've spent the last few weeks running it on real tasks, not toy demos. Here's what it actually does, how to stand it up, and where it's overkill.

What ruflo actually does

ruflo sits on top of Claude Code (via MCP — Model Context Protocol) and gives you a swarm layer: a coordinator process that spawns multiple Claude agents, assigns each one a role, and keeps them in sync through a shared SQLite-backed memory store instead of a shared context window.

The pieces that matter:

• Topologies — how agents talk to each other. Mesh (everyone talks to everyone), hierarchical (a lead agent delegates and reviews), ring, and star. Mesh is the default and the one you'll use 90% of the time.
• Agent roles — coder, tester, reviewer, architect, researcher, and a handful of others. Each spawns as its own Claude instance with a scoped task, not a shared prompt.
• Persistent memory — agents write decisions, schemas, and findings to a shared store so a tester agent can pull the schema the architect agent just decided on, without you copy-pasting it between chats.
• Hooks — pre-task and post-task scripts that run automatically (lint before commit, run tests after a coder agent finishes, that kind of thing).

The pitch is fewer round trips per feature, because agents work in parallel instead of you serially prompting "now write the tests, now review it, now fix the review comments."

Who it's for (and who should skip it)

It's for you if you're running multi-file features with real dependencies — a new endpoint that needs a schema change, implementation, and tests, where those pieces genuinely benefit from separate context. It's also worth it if you're doing repo-wide sweeps (find every place a pattern needs updating) since agents can each own a slice of the codebase concurrently.

Skip it if you're fixing a single function, writing a script, or doing anything you'd finish in one Claude Code turn anyway. The coordination overhead — spinning up agents, writing memory, resolving conflicts — costs real tokens and real wall-clock time. On small tasks that overhead is pure loss.

Getting started

Install and initialize it in a project:

npm install -g ruflo
cd your-project
ruflo init --project api-refactor

That drops a .ruflo/ config directory with a default mesh topology and registers ruflo as an MCP server Claude Code can call. Point Claude Code at it:

claude mcp add ruflo -- ruflo mcp start

From here you drive it either through the CLI directly or by asking Claude Code (now MCP-connected) to orchestrate on your behalf — the second is how most people actually use it day to day.

Worked example: adding an endpoint with tests

Say you need a new /orders endpoint: a schema addition, the route handler, and integration tests. Here's the actual flow.

1. Spin up the swarm with four agents:

ruflo swarm init --topology mesh --max-agents 4

2. Assign roles with scoped tasks:

ruflo agent spawn --type architect --task "Design the orders table schema and the /orders route contract"
ruflo agent spawn --type coder --task "Implement POST /orders per the architect's schema"
ruflo agent spawn --type tester --task "Write integration tests for /orders once the schema is in memory"
ruflo agent spawn --type reviewer --task "Review the /orders implementation for error handling and input validation"

The tester agent doesn't start blind — it polls memory for the schema key the architect writes, so it's writing tests against the real contract, not a guess.

3. Check progress instead of babysitting each agent's output:

ruflo swarm status

This shows each agent's state (running, blocked, done) and flags if the tester is stalled waiting on the architect — which tells you your task descriptions were too vague or too dependent on strict ordering for a mesh topology.

4. Pull the shared decisions if you want to sanity-check them yourself:

ruflo memory query "orders schema"

5. Merge. ruflo doesn't auto-commit anything — you still review the diff and commit like normal. It parallelizes the drafting, not your judgment.

On a task like this, expect the four agents to finish in roughly the time a single agent would take to do just the coding, because the schema, tests, and review run concurrently instead of stacked. The tradeoff: you're paying for four Claude contexts instead of one, so the token bill is higher even though the wall-clock time is lower.

ruflo vs. the alternatives

| | Single Claude Code agent | ruflo (multi-agent) | LangGraph / custom orchestration | |---|---|---|---| | Setup time | None | ~15 min | Hours to days | | Best for | Single-file changes, scripts, debugging | Multi-file features with real dependencies | Custom production agent pipelines with bespoke logic | | Token cost | Lowest | 2-4x a single agent, roughly | Varies, often highest | | Failure mode | You catch mistakes as you go | Agents can duplicate or conflict without clear task scoping | You own every bug in the orchestration layer | | Maturity | Rock solid | Younger, moving fast, occasional rough edges | Mature framework, but you're building the agent logic yourself |

If you're already fluent in one-agent Claude Code workflows and your tasks are small, ruflo adds cost without adding speed. If you're building something bespoke and need full control over agent state machines, LangGraph or a hand-rolled orchestrator gives you more control at a much higher setup cost. ruflo's niche is the middle: real multi-agent leverage without writing your own coordination layer.

Common mistakes

Spawning more agents than the task has independent parts. If the task is really three sequential steps, four "concurrent" agents just wait on each other and you've paid for parallelism you didn't use. Match agent count to genuinely independent workstreams.

Vague task descriptions with a mesh topology. Mesh assumes agents can self-coordinate through memory, but if two agents get overlapping tasks ("build the API" and "build the endpoint") they'll step on each other's files. Scope each task to a distinct file or concern.

Treating swarm memory as a substitute for git and tests. Memory is for agents to hand off context to each other mid-task, not a record of truth. Still review diffs and run your real test suite — a reviewer agent saying "looks good" isn't CI passing.

Ignoring what file access each agent actually has. Agents spawned through MCP inherit real tool permissions. Before you run a swarm on a repo with anything sensitive, check what each agent role can touch — don't assume "tester" agents are read-only by default.

The honest take

ruflo delivers on the core promise — genuine parallel work instead of a chat transcript pretending to be parallel. The memory layer is the real differentiator; it's what makes multi-agent output better than four separate Claude tabs. It's mid on polish, though: topology configuration is still fiddly, and error messages when agents deadlock waiting on memory keys are not great yet.

It's not a replacement for knowing what you want built. It's a way to build it faster once you do.

FAQ

Does ruflo work with Claude Desktop, or only Claude Code?

It's built around MCP, so it works anywhere an MCP client can register a server — Claude Code today, and Claude Desktop wherever MCP tool access is enabled there. Claude Code is the more tested path right now.

How many agents should I run for a typical feature?

Three to five is the practical range for most features — architect, coder, tester, reviewer, and occasionally a researcher. Past that, coordination overhead usually outpaces the speed gained from more parallelism.

Is ruflo the same as just running multiple Claude Code terminals at once?

No — separate terminals don't share memory or task state, so you're manually copy-pasting context between them. ruflo's coordinator and shared memory store are what let agents hand off decisions to each other automatically.

---

→ Ask the index what to build your multi agent stack

→ Free credits for these tools

Written by McKlaud AI. Want to know which AI tools actually fit your business? Get a free AI audit.