If you've ever wished Claude Code could route tasks to specialist agents automatically — without you babysitting every decision — ruflo is worth 10 minutes of your time. This tutorial walks through what ruflo actually installs, how the swarm topology works, and the gotchas I hit on first run.
The Problem: Claude Code Is One Brain by Default
Out of the box, Claude Code is a single context window doing everything — writing tests, reviewing security, refactoring architecture, generating docs. That works fine for small tasks. But the moment a project gets complex, you start noticing it: the model switches mental gears mid-task, loses thread on earlier decisions, or just burns tokens on work another specialist could handle faster.
The first thing I tried was splitting work manually across multiple claude sessions with shared CLAUDE.md files. It helped, but coordination was all manual. Any "memory" between sessions was whatever I remembered to document. Cross-machine collaboration was zero.
What I actually needed was a routing layer — something that intercepts incoming tasks and dispatches them to the right specialist automatically.
The Fix: npx ruflo init
ruflo bootstraps a full agent mesh into your Claude Code environment with one command:
npx ruflo init
That single command does several things under the hood:
- Installs 32 plugins into Claude Code's plugin directory
- Registers 60+ slash commands
- Spins up a vector memory store (the benchmark I saw: ~150x faster retrieval than naive context scanning)
- Wires a hook system into Claude Code's lifecycle events
After init, your .claude/ directory will have a noticeably different shape. Check it:
ls -la .claude/
# You should see:
# plugins/ (32 plugin directories)
# hooks/ (pre/post task interceptors)
# memory/ (vector store files)
# agents/ (specialist agent configs)
If the plugins/ directory is missing, the init silently failed on path resolution. Fix: run from your project root, not a subdirectory.
How the Swarm Actually Routes Tasks
The hook system is the key piece. When you issue a task in Claude Code, ruflo's pre-task hook intercepts it before the main model touches it, classifies it, and routes it to the appropriate specialist agent.
Here's a simplified view of the routing logic (from the hook config):
# .claude/hooks/pre-task.yaml
router:
classify_on: task_description
specialists:
- pattern: "test|spec|coverage"
agent: testing-specialist
- pattern: "security|auth|injection"
agent: security-specialist
- pattern: "refactor|clean|simplify"
agent: refactor-specialist
- pattern: "docs|readme|comment"
agent: docs-specialist
fallback: general-purpose
The hook runs in the background — you don't see it. You write your task normally, and the right agent picks it up. What "agent" means here is a configured context profile with specialized system prompts, tool access, and memory scope.
The specialist count I've seen quoted is 100+. In practice, many are domain composites (e.g., a "database migration specialist" is the SQL specialist + schema-diff tooling + migration history memory). The 100 number counts leaf nodes, not top-level categories.
Cross-Session and Cross-Machine Memory
This is the part that surprised me most. Standard Claude Code memory dies when the session ends. ruflo's vector store persists embeddings across sessions — so an agent that learned your project's naming conventions in Tuesday's session still has that context on Thursday.
The zero-trust mesh for cross-machine collaboration works via signed agent tokens. Each agent on each machine gets a scoped identity. When agents need to collaborate across machines, they authenticate via that token before sharing context — nothing is implicitly trusted.
To verify your memory store is live after init:
# Check vector store is populated
ruflo memory status
# Expected output:
# Vector store: active
# Entries: [N] (grows as you work)
# Index latency: ~0.3ms avg
If ruflo isn't on your PATH after init, add it:
export PATH="$PATH:$(npx ruflo --bin-path)"
Variations and Gotchas
Node version matters
ruflo init requires Node 18+. The error if you're on 16 is unhelpful:
Error: Cannot find module 'node:crypto'
Check your version before running:
node --version
# If < 18, switch via nvm:
nvm use 18
Plugin conflicts with existing CLAUDE.md hooks
If your project already has a CLAUDE.md with custom hook definitions, ruflo init may silently overwrite them. Back up first:
cp CLAUDE.md CLAUDE.md.bak
npx ruflo init
diff CLAUDE.md.bak CLAUDE.md
Merge any custom hooks back manually. The ruflo hook format is YAML-compatible with the standard Claude Code hook spec, so merging is straightforward.
Docker/Linux vs. macOS path differences
On Linux (including Docker), the vector memory store defaults to /tmp/ruflo-memory/ which doesn't persist across container restarts. Set a persistent path explicitly:
RUFLO_MEMORY_PATH=/app/.ruflo-memory npx ruflo init
On macOS, the default path is ~/.ruflo/memory/ which persists normally.
Environment comparison
| Environment | Default Memory Path | Persists? | Notes |
|---|---|---|---|
| macOS | ~/.ruflo/memory/ |
Yes | Works out of box |
| Linux (bare) | ~/.ruflo/memory/ |
Yes | Works out of box |
| Docker | /tmp/ruflo-memory/ |
No | Set RUFLO_MEMORY_PATH |
| CI (GitHub Actions) | /tmp/ruflo-memory/ |
No | Expected — ephemeral by design |
The 60+ commands aren't all immediately useful
After init, running /help in Claude Code will show a much larger command list. Don't try to learn them all upfront. The ones I use daily:
/ruflo status # see which agents are active
/ruflo memory query # debug what the vector store knows
/ruflo route --dry # preview routing without executing
/ruflo agent list # list loaded specialist agents
Closing
The core insight with ruflo is that Claude Code's hook system was designed to be extended — ruflo just builds the entire extension scaffold for you. The npx ruflo init one-liner isn't magic; it's a well-packaged bootstrapper for a routing layer, a vector memory store, and a set of specialist agent configs that would otherwise take days to wire manually.
If you're hitting context window limits or finding that Claude Codeloses track of complex multi-domain tasks, adding a routing mesh is the right architectural move. ruflo is currently the fastest way to get there.
Next up: I'm testing how the cross-machine zero-trust mesh handles partial network failures — specifically, what happens when a remote agent drops mid-task and whether the local agent can recover gracefully without duplicating work.
🐦 Faster updates on X: @baegseungh7061
📚 More in this series: All posts
💌 Subscribe: Follow on X or grab the RSS
댓글
댓글 쓰기