How to Build Ruflo from Source: Complete Monorepo Compilation Guide

To build Ruflo from source, clone the ruvnet/ruflo repository, install pnpm ≥8 and Node ≥20, then run pnpm install followed by pnpm -C v3 run build to compile the TypeScript monorepo.

Ruflo is an open-source AI orchestration platform developed by ruvnet that manages agent swarms, memory systems, and governance policies. When you build Ruflo from source, you compile the entire v3/ monorepo containing the @claude-flow/* workspace packages that power the CLI and core runtime.

Prerequisites for Building Ruflo from Source

Required Tools

You need three core dependencies to compile the repository:

• Node.js ≥20 – Required for the TypeScript compiler and modern ESM support
• pnpm ≥8 – Workspace-aware package manager that handles the monorepo structure defined in v3/package.json
• Git – To clone the ruvnet/ruflo repository

Optional Tools

• Bun – Can replace pnpm for faster installs and builds using bun install and bun run --filter '*' build

Understanding the Ruflo Monorepo Structure

Ruflo v3 uses a monorepo architecture where all core components live under the v3/ directory. The workspace configuration resides in v3/package.json at lines 7-9:

"workspaces": [
  "@claude-flow/*"
]

[v3/package.json #L7-L9]

Key packages in the workspace include:

• @claude-flow/cli – Entry point for the ruflo command-line interface
• @claude-flow/guidance – Policy engine and governance layer
• @claude-flow/memory – Vector search and AgentDB implementation
• @claude-flow/swarm – Swarm coordination primitives and consensus algorithms

Step-by-Step Build Instructions

1. Clone the Repository

git clone https://github.com/ruvnet/ruflo.git
cd ruflo

2. Install the Package Manager

# Install pnpm 8 globally if not present

npm i -g pnpm@8

3. Install Workspace Dependencies

pnpm install

This command reads the workspaces array from v3/package.json and installs dependencies for all @claude-flow/* packages into a shared node_modules structure.

4. Run the Recursive Build

Execute the build script defined at lines 12-13 of v3/package.json:

pnpm -C v3 run build

[v3/package.json #L12-L13]

This runs pnpm -r build, which recursively executes the build script in each workspace package. Typically, each package runs tsc to compile TypeScript sources into the dist/ directory.

5. Verify the Build (Optional)

pnpm -C v3 test

This runs the Vitest suite across all workspaces, validating the compiled binaries against integration tests in v3/__tests__/integration/.

6. Run the CLI

node v3/@claude-flow/cli/dist/index.js --help

After building, you can invoke the ruflo CLI directly from the compiled output or install it globally via npx ruflo@latest init.

Platform-Specific Build Notes

Windows Builds

Ruflo builds on Windows without requiring native build tools (node-gyp) for core functionality because the codebase uses pure TypeScript. However, if you enable optional dependencies like image processing libraries, install the Visual Studio Build Tools first.

Using Bun Instead of pnpm

For faster compilation, replace pnpm commands with Bun:

bun install
bun run --filter '*' build

Bun handles the monorepo workspace syntax differently but achieves the same recursive build across all @claude-flow/* packages.

Build Automation Examples

Minimal Build Script (Bash)

#!/usr/bin/env bash
set -euo pipefail

git clone https://github.com/ruvnet/ruflo.git
cd ruflo

# Install pnpm if missing

command -v pnpm >/dev/null || npm i -g pnpm@8

pnpm install          # workspace install

pnpm -C v3 run build  # recursive build

pnpm -C v3 test       # optional test run

Building a Specific Package

To compile only the CLI package for rapid development:

pnpm -C v3/@claude-flow/cli run build
node v3/@claude-flow/cli/dist/index.js --version

Adding Pre-build Linting

Modify any workspace's package.json to include a prebuild hook:

{
  "scripts": {
    "prebuild": "eslint src/**/*.ts",
    "build": "tsc"
  }
}

When you run pnpm -r build, pnpm automatically executes the prebuild script before TypeScript compilation.

Summary

• Ruflo is built from the v3/ monorepo using pnpm workspaces defined in v3/package.json
• Prerequisites: Node ≥20, pnpm ≥8, and Git
• Build command: pnpm -C v3 run build executes the recursive pnpm -r build script that compiles all @claude-flow/* packages
• Key packages: @claude-flow/cli, @claude-flow/guidance, @claude-flow/memory, and @claude-flow/swarm
• Verification: Run pnpm -C v3 test to execute the Vitest suite across all workspaces
• Alternatives: Bun can replace pnpm for faster installs and builds using bun install and bun run --filter '*' build

Frequently Asked Questions

What is the minimum Node.js version required to build Ruflo from source?

You need Node.js ≥20 to compile Ruflo from source. This version provides the necessary ESM support and runtime features required by the TypeScript compiler and the CLI components.

Can I use npm or yarn instead of pnpm to build Ruflo?

No, you should use pnpm ≥8 because the monorepo structure relies on pnpm workspaces defined in v3/package.json. While npm and yarn support workspaces, the build scripts and dependency hoisting are specifically configured for pnpm. However, you can use Bun as an alternative to pnpm for faster builds.

Where are the compiled JavaScript files located after building Ruflo?

After running pnpm -C v3 run build, each workspace package outputs its compiled JavaScript to a dist/ folder within its respective directory. For example, the CLI binary is located at v3/@claude-flow/cli/dist/index.js, and the memory package compiles to v3/@claude-flow/memory/dist/.

How do I run tests after building Ruflo from source?

Execute pnpm -C v3 test to run the full Vitest suite across all workspaces. This command validates the compiled binaries against unit, integration, and performance tests located in v3/__tests__/integration/ and individual package test directories.

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