Ruflo (by ruvnet, MIT, ~3.8k stars) is a personal multi-agent framework: 100+ specialized agents + self-learning memory + swarm, hooks and autopilot capabilities. Typical use: finish ruflo init once, then keep doing daily work with Claude Code while ruflo handles routing, coordination and memory in the background.

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.

note: verified path here; mainland use the npmmirror branch (npm official 1.2s available overseas)

# Source: Trove detailed guide · verified 2026-08-27
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):

# Source: Trove detailed guide · verified 2026-08-27
npx -y ruflo init --no-signup --no-skills-sh --no-codex-detect
npx -y ruflo --version

Expected output: ruflo v3.38.20

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.

# Source: Trove detailed guide · verified 2026-08-27
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.

# Source: Trove detailed guide · verified 2026-08-27
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.

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.

• Workspace: .claude/ (agents/commands/helpers/skills), .claude-flow/ (config + learning/logs/sessions/workflows), .agents/, .swarm/ (SQLite memory store), .mcp.json (MCP registration), CLAUDE.md, ruvector.db
• HOME: ~/.claude/CLAUDE.md (integration pointer), ~/.claude-flow/
• Background: daemon process (auto-started by doctor/start)

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").

# Source: Trove detailed guide · verified 2026-08-27
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):

# Source: Trove detailed guide · verified 2026-08-27
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.

# Source: Trove detailed guide · verified 2026-08-27
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.

# Source: Trove detailed guide · verified 2026-08-27
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).

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

# Source: Trove detailed guide · verified 2026-08-27
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)

# Source: Trove detailed guide · verified 2026-08-27
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)

# Source: Trove detailed guide · verified 2026-08-27
npx -y ruflo daemon stop

Expected output: Worker daemon stopped

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

# Source: Trove detailed guide · verified 2026-08-27
npx -y ruflo start

Expected output: orchestration system startup state (swarm/agents/memory ready)

Data and directories

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

Same source as the tool-page matrix — 19 pairs total (0 measured compatible / 13 inferred possibly compatible / 6 inferred possibly conflicting); full pairs, states and evidence: Conflict pairs (co-install matrix).

• No standalone handbook yet; for install/uninstall issues first see the agent-executable guide notes

# Source: Trove detailed guide · verified 2026-08-27
npm rm -g ruflo || true; rm -rf -- .claude-flow .swarm ruvector.db 2>/dev/null || true

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

# Source: Trove detailed guide · verified 2026-08-27
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/

• Runtime preflight (needs Node >= 20; pass = output contains a version starting with v)
• Official recommended full CLI path = npx ruflo init (measured passing here); Path A = Claude Code plugin (lite, needs a logged-in environment, not measured; commands from the official README)
• First run downloads via npx automatically (native prebuild deps, ~5 minutes, 1.6GB cache); --no-signup/--no-skills-sh/--no-codex-detect removes interactivity and external registration; init writes workspace .claude/, .claude-flow/, .agents/, .swarm/, .mcp.json, CLAUDE.md, ruvector.db and the HOME ~/.claude/CLAUDE.md pointer block
• Each operation = one command block + expected output; orchestration commands need an LLM provider (configure a provider after method A install)
• Heavy entry: 1.6GB cache + native deps + resident daemon + MCP 333 tools (61K schema tokens) — noticeable disk/memory/resource usage; be cautious in lightweight scenarios

• 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.

• 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.
• 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).

• Verified: local repro log (2026-08-27, npx init + version/help/doctor smoke); local repro log (coexistence with omc/agt/deepcode, CLI layer); local repro log 2026-08-30 (local ollama provider: configure/test connectivity PASS + swarm init/start/status orchestration layer all passed, isolated env, zero key).
• Not tested: swarm execution layer (agents actually running tasks, needs a Claude Code / claude -p execution channel); method B Claude Code plugin (not logged in).

Third-party tutorials are not individually verified; check against this page and official docs.

• 官方 README（npm registry readme 字段，v3.38.20）：Ruflo 完整用法 [官方文档 · Ruflo 官方 · 2026-08-31（包 3.38.20）]
  官方用法全解——init 初始化/start 启动编排/status/agent 管理/swarm 协同/memory 记忆/task 任务/session 会话/mcp 管理/hooks 自学习钩子；进阶：neural 模式训练/security 安全扫描与 CVE 检测/policy 策略引擎（ADR-324 决策账本）/performance 性能画像/embeddings 向量检索