# How to Build Ruflo from Source: Complete Monorepo Compilation Guide

> Build Ruflo from source with our complete monorepo compilation guide. Get step-by-step instructions for cloning, installing dependencies, and compiling Ruflo from the ruvnet/ruflo repository.

- Repository: [rUv/ruflo](https://github.com/ruvnet/ruflo)
- Tags: how-to-guide
- Published: 2026-03-09

---

**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`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/v3/package.json) at lines 7-9:

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

```

[[v3/package.json #L7-L9]](https://github.com/ruvnet/ruflo/blob/main/v3/package.json#L7)

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

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

```

### 2. Install the Package Manager

```bash

# Install pnpm 8 globally if not present

npm i -g pnpm@8

```

### 3. Install Workspace Dependencies

```bash
pnpm install

```

This command reads the `workspaces` array from [`v3/package.json`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/v3/package.json):

```bash
pnpm -C v3 run build

```

[[v3/package.json #L12-L13]](https://github.com/ruvnet/ruflo/blob/main/v3/package.json#L12)

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)

```bash
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

```bash
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:

```bash
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)

```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:

```bash
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`](https://github.com/ruvnet/ruflo/blob/main/package.json) to include a prebuild hook:

```json
{
  "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`](https://github.com/ruvnet/ruflo/blob/main/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`](https://github.com/ruvnet/ruflo/blob/main/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.