Table of Contents
- Installation
- Prerequisites
- Path A: Claude Code Plugin (Lite)
- Path B: Full CLI Install (Recommended)
- Register with Claude Code
- Post-Install: Run Doctor
- Start the Daemon (Optional)
- Troubleshooting Installation
- 'npx' is not recognized (Windows)
- EACCES: permission denied (Linux/macOS)
- MCP server fails to start
- doctor reports missing API key
- Uninstall
Installation
Prerequisites
- Node.js 20+ (download)
- npm 9+ (included with Node)
- Git (for federation and witness verification)
Run npx ruflo@latest doctor after install to verify your setup.
Path A: Claude Code Plugin (Lite)
If you only want to try a few slash commands without the full MCP server:
# In Claude Code, add the Ruflo marketplace
/plugin marketplace add ruvnet/ruflo
# Install ruflo-core
/plugin install ruflo-core@ruflo
This gives you agent definitions and slash commands, but NOT the full MCP server. The memory and swarm tools won't be available to Claude Code.
For the full experience, use Path B.
Path B: Full CLI Install (Recommended)
macOS / Linux / WSL / Git-Bash
curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash
All Platforms (including native Windows)
# Interactive setup wizard
npx ruflo@latest init wizard
# Or non-interactive
npx ruflo@latest init
Install Globally (Optional)
npm install -g ruflo@latest
ruflo init wizard
Register with Claude Code
After npx ruflo@latest init, add Ruflo as an MCP server to Claude Code:
claude mcp add ruflo -- npx ruflo@latest mcp start
This registers the 314 MCP tools (memory, swarm, security, etc.) so they're callable from Claude Code's Task tool.
Post-Install: Run Doctor
Verify everything is working:
npx ruflo@latest doctor --fix
This checks:
- Node.js version (20+)
- npm version (9+)
- Git installation
- Configuration files
- API keys (ANTHROPIC_API_KEY)
- MCP server connectivity
- Disk space
Start the Daemon (Optional)
For background workers and autonomous loops:
npx ruflo@latest daemon start
Check status:
npx ruflo@latest daemon status
Troubleshooting Installation
'npx' is not recognized (Windows)
Use the PowerShell form instead of the curl | bash form:
npx ruflo@latest init wizard
EACCES: permission denied (Linux/macOS)
If you get permission errors:
# Clear npm cache and reinstall
npm cache clean --force
npx ruflo@latest init wizard
MCP server fails to start
Check that Node 20+ is in your PATH:
node --version # should be v20.x or higher
doctor reports missing API key
Set your Anthropic API key:
export ANTHROPIC_API_KEY=sk-ant-...
npx ruflo@latest doctor --fix
Uninstall
npm uninstall -g ruflo@latest
# Or remove from Claude Code:
claude mcp remove ruflo
Next: Quick Start
Getting Started
Reference
Architecture
Advanced
Operations
Ruflo v3.10.1 · npm · GitHub · Benchmarks