Use one package name throughout the setup
Ruflo is the project formerly called Claude Flow. The names still coexist in package metadata, configuration folders and help examples. For a new check, use the ruflo executable consistently rather than switching between commands from different tutorials.
As of October 23, 2026, npm listed ruflo 3.59.17, with Node 20 or later required. Its package depends on exactly @claude-flow/cli 3.59.17. The claude-flow package also reported 3.59.17, but exposes a different executable. These matching versions explain the old name; they do not make every historical installation recipe current.
We installed the pinned Ruflo package in a temporary directory on macOS, using Node 24.5.0. We checked its help, created a minimal project configuration and ran two focused diagnostics. No daemon, model request or authenticated assistant task was started.
Separate CLI, plugin and MCP choices
| Entry point | What you are setting up | What still needs checking |
|---|---|---|
| Ruflo CLI | Project files, configuration and management commands | Generated hooks, client settings and the components your task uses |
| Claude Code plugin | The selected plugin's packaged commands, skills and other components | Plugin scope, enabled state and the installed Claude version |
| MCP connection | A client launches or connects to a server exposing tools | Successful protocol connection and an actual permitted tool result |
| Daemon | Optional background workers | Its lifecycle and the work you explicitly authorize |
“Lite” in the installation wiki names the plugin path. It is not a --lite option in the tested CLI. The current wiki says that path has no MCP server, but the repository's current ruflo-core plugin includes its own MCP declaration. The README now acknowledges that distinction. Inspect the particular plugin instead of assuming all plugins lack MCP.
The current README's console/mods path requires Claude Code 2.1.287 or later. Our installed Claude Code was older, so we did not test that path. Ruflo's Node requirement and a plugin's host-client requirement are separate checks. The official Claude Code plugin guide explains scope and installation-state verification.
Install a pinned CLI in a disposable folder
First confirm the runtime:
node --version
npm --version
The Ruflo installation wiki lists npm 9 or later. Create a separate test directory and install the inspected version there:
mkdir ruflo-check
cd ruflo-check
npm install --ignore-scripts --no-audit --no-fund ruflo@3.59.17
./node_modules/.bin/ruflo --version
./node_modules/.bin/ruflo init --help
The tested version command returned ruflo v3.59.17. --ignore-scripts deliberately prevents dependency installation scripts in this limited check. It is not a guarantee that native memory, embedding or other optional components will work. Follow the upstream dependency requirements before using those components; our test only establishes the CLI and configuration results below.
Using a local executable also makes the tested version explicit. npx ruflo@latest follows a moving tag and may run a later release when you return to the project. Keep the version and generated files together when diagnosing a change.
Initialize with automatic integrations disabled
Review the installed init --help before running initialization. For the tested release, these flags limit the setup to a minimal project and skip optional registrations:
./node_modules/.bin/ruflo init --minimal \
--no-global --no-signup --no-mods --no-plugin-install \
--no-codex-detect --no-skills-sh
./node_modules/.bin/ruflo init check
--no-global skips the global Claude instruction pointer. The other flags skip enrollment, mod installation, automatic Codex setup and skills registration. None of them means “write nothing.” Initialization still creates project instructions, Claude settings, hooks, an MCP declaration and Ruflo runtime configuration.
Our test also used temporary home and configuration directories, passed no model credentials, and compared the user's real Claude/Codex settings before and after. Their hashes were unchanged. That isolation is part of the reported test, not a claim that running the default wizard in an existing project has no side effects.
Inspect these files before opening an assistant in the test directory:
| File | Inspection task |
|---|---|
CLAUDE.md |
Read the instructions the assistant would receive |
.claude/settings.json |
Check generated hooks and permissions |
.mcp.json |
Check the server command and arguments |
.claude-flow/config.yaml |
Check runtime settings and data locations |
The tested init check reported that Ruflo was initialized. It found the Claude settings and runtime YAML. We did not execute the generated hooks or open an authenticated assistant session in that folder. Also, the tested --dry-run help applies to the Grok setup path; do not assume it previews every form of initialization.
Verify individual components
Use diagnostics for the layer you just changed:
./node_modules/.bin/ruflo doctor --json -c node
./node_modules/.bin/ruflo doctor --json -c config
In our run, both returned exit code 0 and JSON checks with status: pass. The Node check identified v24.5.0; the configuration check found .claude-flow/config.yaml. This verifies runtime eligibility and a configuration file, not a working agent team or model connection.
The current help describes doctor --fix as printing suggested commands, while --install can install missing dependencies. Read those suggestions before running them. A missing model credential does not justify reinstalling Node or deleting the configuration directory. Conversely, a configuration pass cannot prove that a provider account is usable.
Connect MCP only when the client needs it
The current README documents a local stdio server with command npx and arguments -y, ruflo@latest, mcp, start. For a repeatable setup using the version above, the shell form is:
npx -y ruflo@3.59.17 mcp start
A stdio server is normally launched by its client. A terminal that waits for protocol input is not itself a successful client connection. Verify the client's server listing, tool discovery and one harmless tool operation separately. We did not run that protocol test or register Ruflo in the user's real client.
For a malformed server declaration, the local configuration checker can inspect JSON without executing command values. It cannot verify that the server or provider works. Avoid registering both the plugin-owned server and a separate CLI server by accident; inspect the client listing and choose the intended integration.
Keep rollback specific to the test
Before adding Ruflo to an existing repository, save its current settings and review the resulting diff. For this disposable test, stop any process you explicitly started, then remove the test folder when finished. Do not delete the user's entire Claude configuration to remove one project integration.
For a real plugin installation, disable or uninstall that plugin in the same scope. For a separately registered MCP server, remove that named registration through the client. Background daemon setup is optional and was outside this test; starting it is a separate decision from creating configuration files.