ruflo

What you will run into

You want orchestration on top of agent CLIs: swarms, agents, memory, MCP, hooks — ruflo is an orchestration platform for Claude Code and other agents. The three things people trip on: the first init downloads native prebuilt dependencies (~5 minutes, 1.6GB npx cache — not stuck, be patient), init writes a LOT of workspace files (that is the full-form design, officially recommended for production), and a daemon auto-starts on doctor/start (stop with ruflo daemon stop). When to use it:

• Full agent orchestration: swarms/agents/memory/MCP/hooks;
• Multi-agent workflows inside a project;
• Wanting an all-in-one platform rather than bolt-on pieces.

When not to use it: single-session single-task work; or you do not want the large workspace write surface — use the plugin lite form (method B) instead.

Path: Quick fix (30s, one command) -> Step by step (skimmable) -> How to confirm it works (success criteria). In a hurry? Jump to Quick fix.

Why this happens

npm CLI (npx -y ruflo). npx -y ruflo init is the full install (with --no-signup --no-skills-sh --no-codex-detect to remove interaction and external registration); first run downloads native prebuilt deps (~5 min, 1.6GB npx cache). npx -y ruflo doctor checks version/Node/npm/Git/config/Memory DB/MCP (⚠ items are warnings, non-blocking); npx -y ruflo start starts the orchestration system (swarm/agents/memory ready, needs a configured LLM provider). Key concepts:

• init: full install with interaction-free flags;
• daemon: background process auto-started by doctor/start;
• doctor: health diagnostics (⚠ non-blocking).

Where it writes (large): workspace .claude/、.claude-flow/、.agents/、.swarm/、.mcp.json、CLAUDE.md、ruvector.db + HOME ~/.claude/CLAUDE.md pointer block.

Step by step

Step 1: init full install (why the three —no flags: remove interaction and external registration)

Why: npx -y ruflo init first run auto-downloads native prebuilt dependencies (~5 minutes, 1.6GB npx cache) — not stuck, be patient. --no-signup --no-skills-sh --no-codex-detect removes interaction and external registration, good for automation/no-account environments. init writes multiple workspace files (see "Why this happens").

npm_config_registry=https://registry.npmmirror.com npx -y ruflo init --no-signup --no-skills-sh --no-codex-detect
npx -y ruflo --version

Expected output: ruflo v3.38.20 Overseas / direct-network branch (drop the npmmirror prefix; npm official 1.2s available):

npx -y ruflo init --no-signup --no-skills-sh --no-codex-detect
npx -y ruflo --version

Expected output: ruflo v3.38.20 After install, confirm:

• npx -y ruflo --version prints v3.38.20;
• workspace shows .claude-flow/ and other skeleton directories.

Stuck? How to recover:

• npx download very slow → first native-deps download ~5 minutes is normal; confirm Node >= 20; mainland use the npmmirror branch;
• workspace gained many files, alarming → this is the full-form design (officially recommended for production); if unwanted, uninstall and take the plugin lite (method B).

Step 2: doctor health check (starts the daemon)

Why: doctor checks version/Node/npm/Git/config/Memory DB/MCP; ⚠ items are warnings, non-blocking. Note: doctor/start auto-start the background daemon; run ruflo daemon stop when done.

npx -y ruflo doctor

Expected output: RuFlo Doctor check items (version/Node/npm/Git/config/Memory DB/MCP); ⚠ items are warnings, non-blocking; then ruflo daemon stop After install, confirm:

• check items output complete, no FAIL (⚠ acceptable).

Stuck? How to recover:

• daemon started, want it stopped → npx -y ruflo daemon stop.

Step 3: Orchestrate a minimal scenario (configure a provider first; commands from --help, not verified here — no API key)

Why: ruflo start starts the orchestration system (swarm/agents/memory ready), with an LLM provider configured first.

npx -y ruflo start

Expected output: orchestration system startup state (swarm/agents/memory ready) After install, confirm:

• orchestration system ready output.

Stuck? How to recover:

• no model error → an LLM provider is needed (deepcode provider/ruflo providers configure the API key).

How to confirm it works

Step 1: Confirm version and skeleton directories

Why: ruflo --version printing v3.38.20 and workspace .claude-flow/ skeleton directories mean the init full install completed.

npx -y ruflo --version
ls -d .claude-flow 2>/dev/null && echo "skeleton: OK" || echo "skeleton: MISSING"

Expected output: ruflo v3.38.20; skeleton: OK Stuck? How to recover:

• version mismatch → rerun init (with --no-signup --no-skills-sh --no-codex-detect);
• skeleton missing → confirm init ran in the target project directory.

Step 2: doctor health check

Why: doctor checks version/Node/npm/Git/config/Memory DB/MCP; no FAIL means the environment is ready; ⚠ items are warnings, non-blocking.

npx -y ruflo doctor

Expected output: RuFlo Doctor check items (version/Node/npm/Git/config/Memory DB/MCP); ⚠ items are warnings, non-blocking Stuck? How to recover:

• FAIL items → fix as prompted (Node version/config);
• daemon started, want it stopped → npx -y ruflo daemon stop.

Other environments

• Network: overseas/direct networks use the npm official branch (verified 1.2s); mainland must use the npmmirror prefix.
• Node version: >= 20 required; first install downloads native deps ~5 minutes + 1.6GB npx cache (heavy, normal).
• Background process: doctor/start auto-start the daemon; stop with ruflo daemon stop.
• Large write surface: workspace .claude/、.claude-flow/、.agents/、.swarm/、.mcp.json、CLAUDE.md、ruvector.db + HOME ~/.claude/CLAUDE.md pointer block — if unwanted, uninstall and take the plugin lite (method B).
• Co-install: CLI layer verified coexisting with omc/agt/deepcode; with the omc plugin form judged possible-conflict (shared .claude/ write surface, not tested); with claude-code-router judged possible-compatible (partially verified 2026-08-30: ruflo workspace settings.json env only sets CLAUDE_FLOW_*, no ANTHROPIC_*; ccr injects HOME settings.json env ANTHROPIC_* after provider config; ccr gateway start/stop + ruflo doctor coexist fine; injection chain not fully verified).

Daily usage

Startup and entry

• Orchestration: npx -y ruflo start;
• Background: daemon (auto-started by doctor/start; stop with daemon stop);
• Command surface: npx -y ruflo --help (30+ commands).

Common operations

Operation 1: View the command list

npx -y ruflo --help

Expected output: starts with Ruflo v3.38.20, includes init/start/agent/swarm/memory/mcp/hooks/daemon, 30+ commands Operation 2: Health diagnostics (verified here; note it starts the background daemon)

npx -y ruflo doctor

Expected output: RuFlo Doctor check items (version/Node/npm/Git/config/Memory DB/MCP); ⚠ items are warnings, non-blocking; then ruflo daemon stop Operation 3: Stop the background daemon (started by doctor/start)

npx -y ruflo daemon stop

Expected output: Worker daemon stopped Operation 4: Orchestrate a minimal scenario (local ollama provider verified 2026-08-30; zero key)

npx -y ruflo start

Expected output: orchestration system startup state (swarm/agents/memory ready; verified 2026-08-30: providers configure/test local endpoint PASS → swarm init → swarm start → swarm status all green, evidence local repro log 2026-08-30) Operation 5: Check swarm status (verified)

npx -y ruflo swarm status

Expected output: status table (Performance Metrics: Elapsed Time 0s / Success Rate no data; Coordination: Messages Sent 0 / Consensus Rounds 0 — "no data"/0 columns are normal before tasks actually run) Operation 6: Stop a swarm (verified pitfall: Swarm ID is required)

npx -y ruflo swarm stop <Swarm ID>

Expected output: swarm stop confirmation (verified: bare ruflo swarm stop fails with [ERROR] Swarm ID is required; get the ID from swarm status or the init output)

Data and directories

• Workspace: .claude-flow/, .agents/, .swarm/, .mcp.json, CLAUDE.md, ruvector.db;
• HOME: ~/.claude/CLAUDE.md (Ruflo pointer block), ~/.claude-flow/.

Uninstall & cleanup

note: npm package uninstall runs automatically (idempotent); workspace-own files (.claude-flow/ .swarm/ ruvector.db) are removed when running this uninstall from the ruflo-init directory; common-name files per the manual checklist below

npm rm -g ruflo || true
rm -rf -- .claude-flow .swarm ruvector.db 2>/dev/null || true
command -v ruflo >/dev/null 2>&1 && echo "ruflo 仍存在" || echo "ruflo removed: OK"

Expected output: ruflo removed: OK Manual checklist (common-name files, may contain other user config, not auto-deleted):

• Workspace: .claude/ (ruflo-generated agents/commands/helpers/settings.json/skills items), .agents/, .mcp.json (remove the claude-flow registration section), CLAUDE.md (remove the Ruflo pointer)
• HOME: ~/.claude/CLAUDE.md (remove the Ruflo Integration pointer block), ~/.claude-flow/

Dependency warnings

• Version: [3.38.20, 3.38.20] locked (verified collection version).
• Environment: Node >= 20; first install downloads native deps ~5 minutes + 1.6GB npx cache (heavy).
• Network: npm official 1.2s available (overseas); mainland use the npmmirror branch.
• Write surface (large): workspace .claude/、.claude-flow/、.agents/、.swarm/、.mcp.json、CLAUDE.md、ruvector.db + HOME ~/.claude/CLAUDE.md pointer block; also: merely running --version/--help writes ~/.claude-flow/update-state.json in HOME (update-check state, confirmed by isolated verify 2026-08-31).
• Background process: daemon (auto-started by doctor/start, stopped by daemon stop).
• Co-install: CLI layer verified coexisting with omc/agt/deepcode (local repro log); with the omc plugin form sharing .claude/ and ~/.claude/CLAUDE.md not tested → possible-conflict; with claude-code-router → possible-compatible (partially verified 2026-08-30: env fields/levels do not overlap; injection chain not fully verified).

FAQ

• Q: npx download very slow/won't install? A: confirm Node >= 20; mainland use the method A npmmirror branch from the install section; first native-deps download ~5 minutes is normal.
• Q: Workspace gained many files after install? A: init is the full CLI install (officially recommended for production), writing .claude/.claude-flow/.agents/.swarm/.mcp.json/CLAUDE.md; if unwanted, use the plugin lite form (method B).
• Q: What is that background process? A: the ruflo daemon (auto-started by doctor/start); stop with ruflo daemon stop.
• Q: Task reports no model? A: an LLM provider is needed (deepcode provider/ruflo providers configure the API key).
• Q: Can it be installed alongside other plugins? A: CLI layer verified coexisting (omc/agt/deepcode, no interference, see local repro log); with the omc Claude plugin form sharing .claude/ and ~/.claude/CLAUDE.md not tested (not logged in here), judged possible-conflict.
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel (usage-report template); project issues go to the author's repository.