Ruflo Install Guide for Claude Code: Plugin, CLI and MCP Setup

Published: 2026-05-04 · Fact-checked: 2026-07-31 · Official repository and release sources

Short answer: Ruflo has two different setup paths. Claude Code plugins add slash commands, skills and agent definitions, but do not register the full Ruflo MCP server. The CLI setup writes project files, installs hooks and registers the broader orchestration runtime. Choose the smaller plugin path to evaluate it; choose the CLI path only after reviewing what it changes.

Correction: The previous version mixed old claude-flow commands with current Ruflo commands, used the invalid init --wizard form, and repeated changing feature counts and prices as fixed facts. This version follows the current project README and removes unsupported cost estimates.

Choose the right Ruflo install path

Path	What it adds	Best for
Claude Code plugin	Selected slash commands, skills and agent definitions; no Ruflo MCP registration	Trying one capability with a smaller workspace footprint
CLI initialization	Project configuration, hooks, MCP server, daemon and broader Ruflo runtime	A deliberate full evaluation in a disposable branch or repository
MCP registration only	Registers `ruflo@latest mcp start` with Claude Code	Users who already understand and want the MCP surface

The project changes quickly. Check the official release page and the package version before copying any command from a third-party guide.

Prerequisites and safe preparation

Install a current supported Node.js and npm release plus Claude Code.
Commit or back up the project before initialization. The full CLI path can create or modify .claude/, .claude-flow/, CLAUDE.md, helpers and settings.
Start in a disposable repository without production credentials or private customer data.
Review every tool permission, hook and background worker before enabling it in a real codebase.

To see the package version that npm currently serves:

npm view ruflo version

Path A: install Ruflo as Claude Code plugins

Inside Claude Code, add the official marketplace and install only the plugins you need:

/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-swarm@ruflo
/plugin install ruflo-rag-memory@ruflo

This is the lighter path documented by the project. It does not register MCP tools such as memory storage or swarm initialization. That distinction explains many reports where slash commands appear but Ruflo MCP tools do not.

Path B: initialize the full Ruflo CLI

The current cross-platform interactive command is:

npx ruflo@latest init wizard

For a non-interactive initialization, the project documents:

npx ruflo@latest init

A global installation is optional:

npm install -g ruflo@latest

Why this guide does not recommend piping directly to a shell: Ruflo's README also publishes a curl | bash installer for POSIX shells. Running a network response directly in a shell gives you less opportunity to inspect the script. The npx ... init wizard route is easier to review and works on native Windows as well as macOS and Linux.

Add the Ruflo MCP server to Claude Code

The canonical command in the current README and user guide is:

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

Then inspect the registration rather than assuming it succeeded:

claude mcp list

Already have a JSON snippet but Claude rejects it? Run it through the MCP Config Doctor to check the wrapper, argument types, environment references and transport before starting Ruflo.

If startup is slow on a first run, distinguish package-download time from an MCP protocol failure. Re-run the package command directly, record the first error, and verify that your shell can find Node and npm.

Common setup problems

Symptom	Likely cause	Check
`init --wizard` is rejected	Old syntax	Use `init wizard`; `wizard` is a subcommand.
Plugin commands exist but MCP tools do not	The plugin-only path does not register the MCP server	Use the documented MCP registration or full CLI path.
`bash` is not recognized on Windows	The POSIX installer was copied into PowerShell or cmd	Use `npx ruflo@latest init wizard`.
MCP startup times out	Cold npm resolution, stale registration or platform command differences	Test `npx ruflo@latest mcp start` directly and compare the generated command with current release notes.
Unexpected files or hooks appear	The full CLI path was used	Review the git diff and generated settings before accepting them.

Can Ruflo use a local LLM?

The repository documents multi-provider routing and local-model options including Ollama-compatible workflows. That does not mean every agent or tool runs locally by default. Check the selected provider, endpoint, model and fallback behavior, then disconnect outbound access in a test environment if local-only operation is a requirement.

Do not put provider keys in tracked files. Confirm which process reads each key, whether prompts or tool outputs leave the machine, and whether background workers can invoke a cloud provider.

Is Ruflo free, and is it worth using?

The repository is published under the MIT license. Ruflo software being open source does not make model calls, hosted services or infrastructure free. Actual cost depends on the providers and workflows you enable; measure it from provider billing and Ruflo's own logs instead of relying on a fixed monthly estimate.

Ruflo is a reasonable experiment when one task can be split into independently verifiable work and the coordination overhead is measurable. It is a poor fit when one agent already solves the task, the repository contains sensitive data, or nobody will review the generated hooks, permissions and output. Start with one plugin and one benchmark task, then compare completion quality, tokens, latency and review effort against plain Claude Code.

Five-minute evaluation checklist

Create a clean branch or disposable repository.
Install one plugin or run the interactive wizard—do not enable everything.
Inspect the file diff, MCP registration and hooks.
Run one bounded task with a known expected result.
Record tool calls, model/provider use, elapsed time, cost and human corrections.
Remove the experiment if it does not beat the simpler baseline.

Official references

Feature counts, commands and package behavior can change quickly. This page was checked against the linked project sources on July 31, 2026; the official repository remains authoritative.