How to Get Started with Ruflo Development: A Complete Setup Guide

Install the CLI with npm install -g ruflo, scaffold a project using npx ruflo@latest init --wizard, and launch the development environment with npm run dev to start building multi-agent applications.

Ruflo serves as the re-branded entry point for the Claude Flow multi-agent platform, distributed as an NPM package that proxies the full @claude-flow/cli toolchain. Whether you are extending the Model Context Protocol (MCP) bridge or customizing the SvelteKit frontend, this guide covers the essential steps to bootstrap your ruflo development environment using the ruvnet/ruflo repository.

What Is Ruflo?

Ruflo is an NPM package that acts as a thin wrapper around the Claude Flow CLI. When you run the ruflo command, bin/cli.js simply re-exports the real CLI from v3/@claude-flow/cli/bin/cli.js. This architecture allows the ruflo ecosystem to leverage the robust multi-agent orchestration of Claude Flow while maintaining a distinct branding and entry point for the ruvnet organization.

Prerequisites for Ruflo Development

Before installing the CLI, ensure your environment meets the following requirements:

• Node.js version 18 or higher (required for the MCP bridge and SvelteKit build tools)
• npm or yarn for package management
• Git for cloning the repository and managing project versions

Installing the Ruflo CLI

You can install the CLI globally for repeated use, or invoke it on-demand via npx.

Global Installation

npm install -g ruflo

This adds the ruflo command to your system path, allowing you to run ruflo init from any directory.

One-time Usage with npx

npx ruflo@latest <command>

Use this approach when you want to ensure you are always running the latest version without maintaining a global installation.

Creating Your First Ruflo Project

Using the Interactive Wizard

The fastest way to start ruflo development is with the built-in scaffolding wizard:

npx ruflo@latest init --wizard

This command performs several setup tasks automatically:

1. Creates a new project directory with a standard structure
2. Generates a starter .env.local file from the template
3. Installs required Node modules for the bridge and frontend
4. Configures the SvelteKit development environment

Project Structure Overview

After initialization, your project contains the following key directories:

• src/mcp-bridge/ – Node.js bridge implementing the Model Context Protocol server (index.js)
• src/ruvocal/ – SvelteKit 2 frontend application providing the chat UI
• src/ruvocal/src/lib/ – Shared libraries including APIClient.ts and type definitions

Configuring Environment Variables

Required API Keys

Before running the development server, copy the example environment file and fill in your credentials:

cp .env.example .env.local

The .env.example file in the repository documents every required and optional variable, including:

• OpenAI API key for LLM inference
• Google API credentials for additional model providers
• MongoDB connection string for persistent memory storage

MCP Tool Groups

Ruflo organizes capabilities into MCP tool groups that you can enable or disable via environment variables:

• MCP_GROUP_AGENTS – Controls access to multi-agent orchestration tools
• MCP_GROUP_MEMORY – Enables persistent context and memory features

Set these to true or false in your .env.local to customize the bridge's exposed functionality.

Running the Development Server

Start the full development environment with:

npm install   # Install bridge dependencies if not already done

npm run dev   # Launches the bridge + SvelteKit dev server

This command starts two processes:

1. The MCP Bridge (src/mcp-bridge/index.js) – Runs the Model Context Protocol server that exposes tools to LLMs
2. The SvelteKit Frontend – Serves the chat UI on http://localhost:5173 by default

For hot-reloading of the bridge process specifically, use:

npm run dev:bridge

Understanding the Ruflo Architecture

Entry Point and CLI Proxy

The ruflo command you invoke is a thin stub located at bin/cli.js. This file simply re-exports the real CLI implementation from v3/@claude-flow/cli/bin/cli.js, allowing the package to proxy all commands to the underlying Claude Flow toolchain while maintaining the ruflo branding.

MCP Bridge Server

Located at src/mcp-bridge/index.js, the bridge implements the Model Context Protocol. This Node.js process starts when you run npm run dev and exposes agent tools, memory systems, and orchestration capabilities to connected LLMs via the MCP specification.

Frontend and API Client

The user interface is a SvelteKit 2 application located in src/ruvocal/src/. Key architectural components include:

• APIClient.ts – A thin, typed wrapper around fetch that constructs endpoint objects for the /api/v2 REST layer. It includes a handleResponse utility that converts raw JSON into typed objects and throws on HTTP errors.
• types/Settings.ts – Defines the persisted user configuration structure, including model overrides, streaming mode preferences, and UI state.

Building and Testing

Production Builds

When you are ready to deploy, generate an optimized production bundle:

npm run build   # Creates a static asset bundle in .svelte-kit

npm run preview # Serves the built bundle locally on http://localhost:4173

The preview command allows you to inspect the production build locally before deployment.

Running Tests

The repository includes a Vitest test suite. Execute all tests with:

npm run test

For targeted development, run a single test file in watch mode:

npx vitest --watch src/ruvocal/src/lib/utils/tree/buildSubtree.spec.ts

This approach is documented in the CLAUDE.md developer guide and is useful when extending tree utilities or other specific modules.

Summary

• Ruflo is an NPM wrapper around the Claude Flow CLI, providing a branded entry point for multi-agent development.
• Installation requires Node.js 18+ and uses either npm install -g ruflo or npx ruflo@latest.
• Project scaffolding is handled by ruflo init --wizard, which creates the directory structure and .env.local configuration.
• Development workflow uses npm run dev to start both the MCP bridge (src/mcp-bridge/index.js) and the SvelteKit frontend.
• Key architectural files include bin/cli.js (entry proxy), APIClient.ts (typed REST wrapper), and types/Settings.ts (configuration schema).
• Testing and building leverage Vitest (npm run test) and standard SvelteKit build commands (npm run build and npm run preview).

Frequently Asked Questions

What is the difference between Ruflo and Claude Flow?

Ruflo is the re-branded NPM package entry point for the Claude Flow multi-agent platform. While Claude Flow provides the underlying CLI toolchain located at v3/@claude-flow/cli/bin/cli.js, Ruflo wraps this functionality in the ruvnet namespace. When you run ruflo commands, bin/cli.js simply proxies to the Claude Flow implementation, maintaining identical functionality under the new branding.

Do I need to install Claude Flow separately?

No. When you install Ruflo via npm install -g ruflo or use npx ruflo@latest, the package automatically includes the @claude-flow/cli dependency. The bin/cli.js stub handles the delegation, so you only interact with the ruflo command while the underlying Claude Flow tools execute in the background.

How do I enable specific MCP tool groups?

MCP tool groups are controlled through environment variables defined in your .env.local file. According to the .env.example template, you can toggle functionality by setting variables such as MCP_GROUP_AGENTS and MCP_GROUP_MEMORY to true or false. These settings determine which capabilities the MCP bridge (src/mcp-bridge/index.js) exposes to connected LLMs when you run npm run dev.

Can I use Ruflo without the SvelteKit frontend?

Yes, though the standard development workflow (npm run dev) launches both the MCP bridge and the SvelteKit frontend. If you only need the backend MCP server, you can start the bridge process independently. The src/mcp-bridge/index.js file implements the Model Context Protocol server, and you can configure it solely through environment variables without serving the UI components located in src/ruvocal/.

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