How to Set Up a Development Environment for Ruflo

To set up a Ruflo development environment, install Node.js 20+, the Claude Code CLI, and run the automated installer at scripts/install.sh with the --full flag to configure global access, MCP integration, and project scaffolding.

Ruflo (formerly Claude Flow) is an enterprise-grade, multi-agent AI orchestration platform built on top of Claude Code. It ships with a self-learning kernel, vector memory (HNSW), and full MCP (Model Context Protocol) integration. To begin contributing or developing with this framework, you must configure Node.js 20 or higher, the Claude Code CLI, and the Ruflo package itself.

Prerequisites

Before running the installer, verify your system meets these baseline requirements as enforced by scripts/install.sh:

• Node.js 20 or higher: The installer checks your version by parsing node -v and comparing it against the minimum threshold at lines 50-55. If you lack Node 20, the script suggests installing fnm (Fast Node Manager) to obtain it (lines 58-62).

• npm: The npm -v check occurs at lines 73-77 to ensure package management capabilities are available.

• Claude Code CLI: The installer attempts claude --version and, if missing, automatically installs the CLI globally via npm install -g @anthropic-ai/claude-code (lines 82-97).

Installation Methods

The scripts/install.sh script supports four distinct workflows via the install_package() function (lines 24-40). Choose the mode that matches your development needs:

Global Install (--global) Adds the ruflo command permanently to your PATH using npm install -g ruflo@<version>. This is the recommended approach for daily development.

Npx-Only (Default) Runs without flags to execute Ruflo via npx without a permanent installation, storing the package in the temporary npx cache (lines 42-45). Ideal for CI/CD pipelines or one-off testing.

Minimal Profile (--minimal or -m) Skips optional heavy dependencies by appending --omit=optional to the npm install command (lines 27-33). Use this when you need a lightweight agent runtime without extended AI libraries.

Full Setup (--full or -f) Executes a complete configuration by setting GLOBAL=1, SETUP_MCP=1, RUN_DOCTOR=1, and RUN_INIT=1 (lines 71-76). This installs globally, configures the MCP server, runs diagnostics, and bootstraps a new project.

Run the full setup with:

curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/claude-flow@main/scripts/install.sh \
  | bash -s -- --full

MCP Server Configuration

While optional, configuring the MCP server unlocks Ruflo's full capabilities by allowing Claude Code to invoke its 170+ specialized tools. When using --full, the installer automatically executes the setup_mcp_server() function (lines 30-38) to register Ruflo:

claude mcp add ruflo -- ruflo mcp start

If you installed via npx or need to configure manually later, use:

claude mcp add ruflo -- npx -y ruflo@latest mcp start

This handshake is critical because Ruflo's architecture—spanning the CLI entry point at bin/cli.js, the swarm manager, and the HNSW vector memory stack—relies on MCP for inter-agent communication.

Verify and Initialize Your Environment

After installation, validate the setup using built-in diagnostic commands:

Run System Diagnostics The ruflo doctor command (or npx ruflo@latest doctor for non-global installs) executes internal health checks for dependencies, network connectivity, and MCP status. The installer triggers this automatically when RUN_DOCTOR=1 is set (lines 48-51).

Bootstrap a Project Initialize a new Ruflo workspace with ruflo init --yes (or npx ruflo@latest init --yes). This creates the .claude/ configuration directory, default agent definitions, and project scaffolding automatically (lines 64-71).

Both commands should return green check-marks and version confirmations indicating successful installation.

Architectural Context

Ruflo's runtime consists of interconnected layers that require specific environmental support. The Node.js 20+ requirement ensures compatibility with compiled WASM kernels in @ruvector/* packages. The Claude Code CLI provides the foundational MCP host capability. Without these, the swarm manager (which coordinates 60+ specialized agents using hierarchical and mesh topologies) cannot initialize the memory stack (HNSW → SQLite → AgentDB → ReasoningBank) or execute tasks from bin/cli.js.

Summary

• Install Node.js 20+ and verify with node -v (checked in scripts/install.sh lines 50-55).

• Ensure npm is available and install the Claude Code CLI globally.

• Execute the Ruflo installer with --full for complete setup or choose specific flags for minimal installs.

• Configure the MCP server to enable Claude Code integration with Ruflo's tool suite.

• Run ruflo doctor to validate the environment and ruflo init --yes to create your first project.

Frequently Asked Questions

What is the minimum Node.js version required for Ruflo development?

Ruflo requires Node.js 20 or higher. The installer script at scripts/install.sh explicitly parses node -v and validates the version at lines 50-55, exiting with instructions to use fnm if your version is outdated.

How do I install Ruflo without adding it to my global PATH?

Use the npx-only installation method by running the installer without the --global flag. This caches the package temporarily and allows you to invoke commands via npx ruflo@latest without permanent installation, as handled in lines 42-45 of scripts/install.sh.

What does the ruflo doctor command verify?

The ruflo doctor command runs comprehensive diagnostics checking dependency health, network connectivity, MCP server accessibility, and WASM kernel load status. It is implemented in the installer logic at lines 48-51 and executes automatically when using the --full installation flag.

Is the Claude Code CLI mandatory for Ruflo?

Yes. The Claude Code CLI (@anthropic-ai/claude-code) is required because Ruflo functions as an MCP server that communicates through Claude Code's host interface. The installer checks for this dependency at lines 82-97 and automatically installs it if missing, as the MCP handshake fails without this component.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}