Ruflo: What a Swarm Orchestration Layer Actually Adds to Claude Code

Claude Code is a single-threaded executor with a temporary context window. It does the work, but it doesn't remember what worked last month, it doesn't coordinate five agents editing the same repository, and it doesn't run anything while you sleep. Ruflo is a bet that those three gaps (memory, coordination, background execution) deserve a dedicated layer instead of ad-hoc prompting.

I've been running Ruflo v3 alongside Claude Code for about two weeks. Long enough to see the daily mechanics, not long enough to call anything a habit. Two weeks is also the honest window for a tool like this: past the installation honeymoon, before sunk-cost bias sets in. This is what the layer actually does, where the marketing vocabulary ("hive-mind", "neural patterns") maps to real mechanisms, and where I'd tell you not to bother.

The coordination layer: memory, hooks, and routing above; Claude Code executors below.

The mental model: ledger, not executor#

The single most important framing, and the one Ruflo's own docs bury under swarm terminology, is the division of labor:

• Claude Code executes. It reads files, writes code, runs tests. Nothing changes there.
• Ruflo coordinates. It is the ledger and policy decision point: which agent owns which files, what was learned in previous sessions, which background worker should run after a change, which model tier a task deserves.

Ruflo never touches your code directly. Every Ruflo call is followed by Claude Code (or a spawned subagent) doing the actual work. If you remember one thing from this article, make it that sentence. Most disappointment with orchestration frameworks comes from expecting the coordinator to be the worker.

Getting it running#

Setup is three commands, and the order matters. First the project scaffold, then the MCP wiring, then the health check:

# 1. Scaffold: writes .claude-flow/, .swarm/, hook registrations, CLAUDE.md section
npx ruflo@latest init --wizard

# 2. Register the MCP server so Claude Code can call Ruflo tools directly
claude mcp add claude-flow -- npx -y ruflo@latest mcp start

# 3. Verify: catches missing permissions, stale configs, broken hook paths
npx ruflo@latest doctor --fix

The wizard asks about topology, agent limits, and memory backend; I kept the defaults (hierarchical, hybrid memory, HNSW indexing on). After init, add .claude-flow/, .swarm/, and the vector database files to .gitignore. The wizard suggests this, but check anyway, because a committed memory.db full of session history is not something you want in a public repository.

That's the floor. The ceiling, actually using the full surface, is a workflow rather than more installation.

Before a task, recall and route. The hooks automate this, but the manual form shows what's happening:

npx ruflo@latest memory search --query "payment saga retry" --namespace patterns
npx ruflo@latest hooks route --task "add idempotency to the settlement handler"

For multi-file work, initialize a swarm and let agents claim scopes instead of prompting one session to "be careful":

npx ruflo@latest swarm init --topology hierarchical --max-agents 8 --strategy specialized

The practical threshold I use: three or more files changing, or more than one concern (implementation plus tests plus review) worth separating. Below that, a swarm is ceremony.

After a success, close the learning loop. This is the step everyone skips, and it's the whole point of the memory layer:

npx ruflo@latest memory store --namespace patterns --key "settlement-idempotency" \
  --value "dedupe on message-id at the handler boundary, not in the saga"
npx ruflo@latest hooks post-task --task-id settlement-fix --success true --store-results true

For background sweeps, start the daemon deliberately and let the TTL kill it:

npx ruflo@latest daemon start          # 12h TTL by default, leave it
npx ruflo@latest daemon status --all   # audit what's actually running

Skip nothing in that loop and the tool compounds; skip the store/post-task step and you've installed a database that never gets written to. Most of the 26 commands and 300+ MCP tools hang off these five verbs. The deeper tier (analyze, policy, guidance, the neural cost router) gets its own section below, because it deserves better than a name-drop. But make the loop a habit first.

What you actually get#

Persistent memory with vector search#

Ruflo keeps a SQLite database (.swarm/memory.db) with namespaced key-value entries and HNSW-indexed embeddings on top. Before a task, you (or a hook) search it; after a success, you store what worked:

npx ruflo@latest memory search --query "mermaid build pipeline" --namespace patterns
npx ruflo@latest memory store --namespace patterns --key "mdx-mermaid" \
  --value "mermaid needs chromium at build time; keep toolchain in serverExternalPackages"

This overlaps with what I already do in Obsidian, where one well-maintained note beats ten fragments. The retrieval path is different, though. Vault notes are for humans and agents reading deliberately; Ruflo memory is for hooks injecting relevant patterns automatically at session start. In my sessions that shows up as an [INTELLIGENCE] block listing patterns matched against the task before I've typed anything.

Two weeks in, the honest score: most injected recalls are noise. "Frequently edited: metadata.ts" tells me nothing I don't know. But one recall paid for the setup. This blog's build renders mermaid diagrams to inline SVG at build time, which needs chromium and a toolchain pinned in serverExternalPackages; I'd hit that failure mode once, stored the pattern, and forgot about it. Weeks later, in a session touching the MDX pipeline, the pre-task hook surfaced it before the build broke, and the agent avoided "simplifying" the config that only exists to prevent a bundling failure. One good recall out of dozens of trivial ones. Whether that ratio justifies the layer depends on how expensive your worst re-discovery is.

Hooks that route and learn#

Ruflo registers Claude Code hooks (session start, pre/post task, post edit). The interesting ones are hooks route, which suggests an agent type and model tier for a task description, and hooks post-task, which feeds outcomes back into the pattern store. The routing table is blunt. It's keyword-driven with a confidence score, and it says so: "Default routing - no specific keyword matched, confidence 30%". I find the honesty refreshing. It's a heuristic, not magic.

Background workers via the daemon#

The optional daemon runs interval workers: map (codebase mapping), audit (security), optimize, testgaps, consolidate (memory compaction). On this very repository, over one night:

The millisecond durations tell you these are cheap checks that decide whether to dispatch real work, not the work itself. When a worker does dispatch, it spawns a headless claude session, and that session consumes tokens for as long as it runs. That's the fine print: an always-on daemon is an always-on bill. Ruflo ships with a 12-hour TTL by default for exactly that reason.

Swarm coordination, the part with the vocabulary#

Topologies (hierarchical, mesh), consensus protocols, a "hive-mind". Strip the branding and the useful core is a small set of concurrency rules that any team of writing agents needs:

• Never two writers in one worktree. Each writing agent gets an isolated worktree and explicit file ownership.
• Read-only research runs concurrently and reports to the owner.
• Only one integration owner touches shared manifests and lockfiles.
• Claims and leases coordinate ownership; they don't authorize side effects.

These rules are worth adopting even if you never run a sixteen-agent swarm. I use them at swarm size two or three: an architect, a coder, a reviewer, wired together with direct messages rather than polling. The elaborate topologies exist; whether anyone needs Byzantine fault tolerance for a refactor is a question I'll leave open.

The advanced surface (v3.34.0)#

Everything above is the daily loop. Ruflo v3.34 ships a second, deeper tier that most reviews wave at and skip. Some of it is further along than the naming suggests, so here it is, capability by capability, each with the use case where I'd actually reach for it.

The advanced tier: MinCut boundaries on top, policy gate and decision receipts in the middle, the autonomous hive below.

analyze: graph algorithms on your codebase#

Tree-sitter AST parsing, complexity metrics, and the interesting part: MinCut boundary detection and Louvain community detection over the dependency graph.

npx ruflo@latest analyze boundaries src/     # natural seams via MinCut
npx ruflo@latest analyze modules src/        # module communities via Louvain
npx ruflo@latest analyze circular src/       # dependency cycles
npx ruflo@latest analyze diff                # change-risk classification of the working diff

Use case: planning an extraction from a monolith. Instead of arguing about where the service boundary goes, run MinCut and argue with the graph. analyze diff is the sleeper: classify a diff's risk before review and route high-risk changes to a heavier review lane. Of the whole advanced tier, this is the subsystem I'd rank most immediately useful, because it works standalone, without a swarm, without memory, without the daemon.

policy: budgets and a decision ledger#

An agentic policy engine (ADR-324) with three modes (legacy, observe, enforce), atomic budget ceilings, and signed decision receipts:

npx ruflo@latest policy init --mode observe   # watch first, block later
npx ruflo@latest policy budget set '{"id":"daily-model","action":"model.call","maxCostUsd":10,"periodMs":86400000}'

Use case: the daemon-cost problem from the previous section, solved structurally. A $10/day ceiling on model calls turns "I hope the daemon didn't burn my quota" into a hard guarantee, and every allow/deny decision lands in a verifiable ledger. Start in observe, read a week of receipts, then flip to enforce. If you run any always-on agent workload, this is the first advanced feature to turn on.

guidance: your CLAUDE.md, compiled#

This one surprised me. It treats CLAUDE.md as source code: compiles it into a policy bundle (constitution plus retrievable shards), serves only task-relevant shards per prompt, and can A/B test two versions of your CLAUDE.md against each other.

npx ruflo@latest guidance compile
npx ruflo@latest guidance retrieve -t "fix the settlement saga retry"
npx ruflo@latest guidance optimize          # structure/coverage/enforceability audit
npx ruflo@latest guidance ab-test           # behavioral diff of two CLAUDE.md versions

Use case: every long-lived CLAUDE.md bloats until the agent stops following it. Mine included. Shard retrieval means the agent gets the five rules relevant to this task instead of all three hundred lines, and ab-test replaces "I think the new wording works better" with a measured comparison. Anyone maintaining agent instructions at team scale should look at this regardless of whether they adopt the rest of Ruflo.

security: injection defense for multi-agent setups#

Beyond the standard scan/CVE/secrets fare, three subcommands target a threat model most people haven't priced in yet: agents attacking each other. composition-scan checks registered MCP tool descriptions for cross-tool prompt-injection signatures; channel-scan inspects inter-agent messages for injection payloads; scan-plan gates agent-emitted plans against injected steps.

Use case: the moment you run a swarm where agent A's output becomes agent B's input, your attack surface is no longer just the user prompt. A poisoned MCP tool description or a manipulated hand-off message propagates through the whole pipeline. These scanners are the only tooling I've seen that treats that as a first-class problem.

neural and route: learned cost routing#

Strip the branding ("MicroLoRA", "Flash Attention", WASM SIMD) and the operationally interesting piece is the cost-optimal router (ADR-148/149). It learns from your task trajectories which model tier each task class actually needs, tracks realized savings, and projects costs:

npx ruflo@latest route "write tests for the outbox relay"   # Q-Learning agent pick
npx ruflo@latest neural router cost-savings                 # what the routing saved
npx ruflo@latest route feedback --task-id t-42 --outcome good  # close the loop

Use case: you're paying Opus prices for Haiku work more often than you think. A router that learns from your history that mechanical test scaffolding needs a small model while a saga redesign needs a big one, and shows the savings ledger to prove it, pays rent in a way "neural pattern training" as a phrase never will. The catch: it needs the feedback loop, same as memory. No feedback means no learning.

hive-mind and autopilot: the unsupervised end#

The queen-led consensus hive and the persistent-completion loop (autopilot re-engages agents until the task list is empty, with iteration and timeout caps) are the genuinely autonomous tier:

npx ruflo@latest hive-mind spawn --claude -o "migrate the module to the new event schema"
npx ruflo@latest autopilot enable && npx ruflo@latest autopilot config --max-iterations 50 --timeout 180

Use case: an overnight burn-down of a well-specified, well-tested backlog. Schema migrations, dependency bumps, lint-debt cleanup: tasks that are verifiable, on a branch, with a bounded blast radius. This is also exactly where policy budgets stop being optional. Unattended iteration plus no spend ceiling is how you fund someone else's GPU cluster. I've run this tier the least, and I wouldn't point it at anything without a test suite that I trust more than I trust the agents.

The pattern across all six: the advanced surface is where Ruflo stops being a Claude Code accessory and becomes infrastructure. Each piece demands the same two things, a feedback signal and a spend guardrail, and rewards you in proportion to how honestly you provide both.

Prompts that pull the levers#

The CLI commands above are the plumbing. Day to day, you mostly don't type them. You prompt Claude Code, and the MCP tools plus hooks decide what fires. Which means prompting is the interface to Ruflo, and vague prompts get you the default 30%-confidence routing I showed earlier. The difference between "the swarm did something" and "the swarm did what I meant" is usually in the prompt naming the capability explicitly.

Single-capability prompts, each aimed at one mechanism:

Before you start: search ruflo memory (namespace "patterns") for anything
about the settlement saga and the outbox relay. List what you found and
what you'll reuse. Only then plan the change.

Run ruflo's analyze on src/modules/billing — boundaries and circular deps.
I want the MinCut seam and every cycle listed before we discuss where the
new payment-provider adapter should live.

Classify the current git diff with ruflo (analyze diff). If the risk class
is anything above low, stop and give me the risk factors instead of
committing.

This CLAUDE.md has grown past 300 lines. Use ruflo guidance optimize on it
and give me: rules that conflict, rules the agent can't enforce, and a
sharding proposal. Don't rewrite anything yet.

Init a ruflo swarm for this feature: hierarchical, 4 agents — researcher,
architect, coder, tester. Pipeline, not fan-out: researcher maps the
current retry logic and messages findings to architect; architect designs
and messages coder; coder implements and messages tester. Each writing
agent gets its own worktree and an explicit file list — coder owns
src/handlers/, tester owns tests/, nobody else writes. I want the agent
names and their file ownership printed before any of them starts.

The swarm prompt encodes the two things that actually prevent chaos: the communication shape (a pipeline of named agents messaging each other, instead of everyone reporting to you) and file ownership declared up front. "Print the ownership map before starting" is the audit trick again. A conflict you can see before execution is a merge you don't have to untangle after.

After we finish this task, store the non-obvious part in ruflo memory:
namespace "patterns", key "doctrine-em-reset", value explaining WHY the
entity manager must be reset after a rollback, not just that it must.
Then run hooks post-task with success=true.

The recall prompt earns a comment: "list what you found and what you'll reuse" is doing real work. Without it, the agent searches memory, silently judges the results irrelevant, and you never learn whether the memory layer is earning its tax. Forcing the recall into the visible output is how you audit the loop.

And the composite, one prompt that exercises the whole stack on a real task:

We're extracting notification logic out of the billing module.

1. Recall: search ruflo memory (namespaces "patterns" and "decisions") for
   billing, notifications, and event schema. Summarize hits in 5 lines.
2. Map: run analyze boundaries + circular on src/modules/billing. Propose
   the extraction seam from the MinCut result, not from intuition.
3. Swarm: init hierarchical, max 4 agents — architect, coder, tester,
   reviewer. Each writing agent gets an isolated worktree and an explicit
   file list; only the architect touches shared manifests.
4. Guard: policy stays in observe mode, but if projected model spend for
   this task exceeds $5, pause and report instead of continuing.
5. Close the loop: after tests pass, store the extraction decision and the
   seam rationale in memory, run hooks post-task, and give me a receipt of
   what was stored.

That's five capabilities in one task (memory, analyze, swarm with ownership rules, policy, the learning loop), and every step produces an artifact you can check. The shape to steal isn't the specific task; it's the skeleton: recall, map, execute with ownership, guard, store. Prompts shaped like that turn Ruflo from a box of tools into a procedure. Prompts shaped like "use your swarm to fix billing" turn it into confetti.

What it costs#

The trade in one desk scene: learned memory on screen, the token counter ticking beside it.

A cost ledger, because every layer has one:

• Setup surface. .claude-flow/, .swarm/, a vector database, hook registrations, MCP server config. That's five new artifact locations in your repository to understand and gitignore.
• Token overhead. Hooks fire on every prompt. Pattern injection, routing calls, post-task learning: each is small, but it's a tax on every session, and the daemon multiplies it if you leave it running.
• Conceptual overhead. The tool ships 300+ MCP tools and 26 CLI commands. The useful daily subset is maybe eight: memory store/search, hooks route, swarm init, agent spawn, daemon start/status, doctor. Finding that subset took longer than installing the tool.
• Trust calibration. "Neural training" and "learning" describe pattern statistics over your task history, not model fine-tuning. Useful, but the expectations the names set need adjusting.

Back-of-envelope for a representative week, since precise attribution is hard once hooks are woven into every prompt. The per-prompt tax (pattern injection, routing call, post-task learning) adds roughly 1-2k tokens per exchange. At my pace, say 150-200 exchanges a week, that's 200-400k tokens weekly before any real work happens: a few dollars at API rates, a meaningful slice of a subscription quota. The daemon is the variable that matters. Idle checks are millisecond-cheap, but each dispatched worker spawns a headless claude session that can burn 50-100k tokens per run. Left on with default intervals, that's the difference between "rounding error" and "second seat on the plan". My rule after two weeks: hooks always on, daemon started explicitly for a working block and left to its 12-hour TTL, never restarted out of habit. Treat these as estimates with generous error bars; the point is the shape, not the digits.

When not to build this#

Skip Ruflo, or any orchestration layer, when:

• Your work is single-file, single-session. A coordinator with nothing to coordinate is pure overhead. Claude Code alone with a good CLAUDE.md covers this.
• You already have a working memory layer. If your vault or .context notes are disciplined, Ruflo's memory adds a second source of truth to keep honest. Two memories that drift is worse than one.
• You can't articulate the concurrency problem you have. "Agents might conflict" is not yet a problem statement. Wait until two agents actually clobber each other's edits; the fix will be obvious and you'll configure exactly what you need.
• Token budget is tight. The daemon and per-prompt hooks are recurring costs. A tight budget is better spent on longer main-session context.

The threshold, roughly: three or more files changing per task, more than one agent writing, and a real need for knowledge to survive across sessions. Below that line, this is architecture without a load.

My verdict after two weeks is a split one, and I think that's the correct shape rather than a cop-out. The memory layer and hooks stay. The per-prompt tax is real but bounded, and one prevented re-discovery per week covers it. The concurrency rules stay as rules, applied at swarm size two or three, without the ceremony of topologies and consensus protocols. The daemon runs only when I explicitly start it for a working block. From the advanced tier, analyze and policy have earned a permanent slot, because graph-informed boundaries and hard spend ceilings solve problems I demonstrably have, and guidance is on the shortlist, because my CLAUDE.md is exactly the bloated instruction file it was built for. The truly autonomous end, hive-mind and autopilot, stays parked until I have a backlog verifiable enough to trust to an unattended loop. "It depends" is the verdict because the package is really six or seven tools sharing a brand, and they earn their keep separately.