How to Troubleshoot Ruflo Installation Problems: Complete Diagnostic Guide

Run npx @claude-flow/cli@latest doctor to automatically diagnose and fix Ruflo installation issues, including Node.js version conflicts, missing API keys, and MCP server misconfigurations.

When installing Ruflo from the ruvnet/ruflo repository, environment mismatches or permission errors can prevent the CLI from functioning correctly. This guide walks you through how to troubleshoot Ruflo installation problems using the built-in diagnostic tools and manual verification steps derived directly from the source code in v3/@claude-flow/cli/src/commands/doctor.ts.

Run the Built-in Health Check with the Doctor Command

The fastest way to identify installation issues is to run the diagnostic suite implemented in doctor.ts. This command evaluates 15 distinct environment checks and provides automated fix suggestions.

# Full diagnostic check

npx @claude-flow/cli@latest doctor

# Show suggested fix commands

npx @claude-flow/cli@latest doctor --fix

What the Doctor Command Checks

According to the source code in v3/@claude-flow/cli/src/commands/doctor.ts, the diagnostic tool validates the following components:

• Node.js version (≥ 20) – Checks process.version at lines 41-48
• npm version (≥ 9) – Executes npm --version at lines 58-66
• Claude Code CLI – Verifies claude --version at lines 55-63
• Git – Checks git --version at lines 58-61
• Config file – Validates JSON at .claude-flow/config.json at lines 71-89
• Daemon PID – Detects running processes or stale PID files at lines 95-107
• Memory DB – Checks existence and size of .claude-flow/memory.db at lines 113-133
• API keys – Verifies ANTHROPIC_API_KEY or CLAUDE_API_KEY at lines 136-152
• MCP servers – Validates claude-flow entry in MCP config at lines 176-200
• Disk space – Checks free space via df -Ph at lines 206-226
• TypeScript – Runs npx tsc --version at lines 232-242
• Platform permissions – Checks executable bits and PowerShell policies at lines 250-267

If any check returns fail or warn, the doctor outputs a one-line fix command (e.g., nvm install 20 && nvm use 20 for Node version issues).

Fix Common Platform-Specific Installation Issues

Linux (Ubuntu/Debian)

If npm is missing or outdated, install Node.js 20+ via Node Version Manager rather than the system package manager to avoid permission conflicts:

# Install nvm if missing

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node 20

nvm install 20 && nvm use 20

# Verify

node --version  # Should print v20.x.x

macOS

Missing Git or Homebrew dependencies are common on fresh macOS installations. Install Homebrew first, then the required tools:

# Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies

brew install git node

# Verify Ruflo doctor passes

npx @claude-flow/cli@latest doctor

Windows PowerShell and Git Bash

Windows users often encounter execution policy restrictions or permission errors when running helper scripts.

PowerShell Execution Policy:

# Check current policy

Get-ExecutionPolicy

# Set to RemoteSigned for current user

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Git Bash Permission Fixes:

If you encounter chmod-style errors in Git Bash, manually set executable permissions:

chmod +x .claude/helpers/*.sh .claude/helpers/templates/*.sh

Alternatively, right-click the script files in Explorer, select Properties, and click Unblock if present.

Validate the Helper System and Permissions

Ruflo ships with a helper layer used by Claude Code. Validate these scripts are executable and correctly configured:

# Linux/macOS validation

./.claude/helpers/claude-flow-v3.sh validate

# Expected output: "All checks passed!"

If validation fails, check the helper documentation in v3/helpers/docs/installation.md for platform-specific setup instructions.

Reinstall Critical Dependencies

Claude Code CLI

If the doctor reports the Claude Code CLI is missing, force a clean reinstall:

# Remove old copy

npm uninstall -g @anthropic-ai/claude-code

# Fresh install

npm install -g @anthropic-ai/claude-code

# Verify

claude --version

MCP Server Registration

If Ruflo-specific tools are invisible in Claude Desktop, verify the MCP server registration:

# List registered servers

claude mcp list

# Should show: claude-flow

If absent, add it manually:

claude mcp add claude-flow -- npx -y @claude-flow/cli@latest mcp start

For VS Code, add the same configuration to .vscode/mcp.json.

Memory Database Initialization

A corrupted SQLite database can cause silent failures. If the doctor warns about the memory DB, reinitialize it:

# Remove corrupted database

rm .claude-flow/memory.db

# Reinitialize with force flag

npx @claude-flow/cli@latest memory init --force

Key Source Files for Deep Troubleshooting

When manual intervention is required, inspect these specific files in the ruvnet/ruflo repository:

File	Purpose	Location
doctor.ts	Implements all 15 diagnostic checks and fix suggestions	v3/@claude-flow/cli/src/commands/doctor.ts
installation.md	Platform-specific helper setup and permission fixes	v3/helpers/docs/installation.md
CLAUDE.md	CLI-to-Claude Code coordination and troubleshooting reference	v3/@claude-flow/cli/CLAUDE.md
claude-flow-v3.sh	Helper script wrapper for validation and status checks	.claude/helpers/claude-flow-v3.sh

Summary

To effectively troubleshoot Ruflo installation problems:

• Start with the doctor: Run npx @claude-flow/cli@latest doctor to identify specific failures across 15 environment checks.
• Fix platform permissions: Use nvm for Node version issues on Linux/macOS, Set-ExecutionPolicy for PowerShell on Windows, and chmod for helper scripts.
• Verify critical components: Ensure the Claude Code CLI is installed, the MCP server is registered, and the SQLite memory database is initialized.
• Consult source files: Reference doctor.ts and installation.md in the ruvnet/ruflo repository for implementation details when automated fixes fail.

Frequently Asked Questions

Why does the Ruflo doctor command report Node.js version errors?

The doctor command checks for Node.js version 20 or higher by reading process.version in v3/@claude-flow/cli/src/commands/doctor.ts. If your system Node is older, install version 20+ via nvm install 20 && nvm use 20 or download it directly from nodejs.org.

How do I fix PowerShell execution policy errors when installing Ruflo?

Windows PowerShell defaults to the Restricted policy, which prevents script execution. Run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned to allow locally created scripts to run while requiring remote scripts to be signed. This is documented in v3/helpers/docs/installation.md.

What should I do if Ruflo tools don't appear in Claude Desktop?

This indicates the MCP server is not registered. Run claude mcp list to verify; if claude-flow is missing, add it with claude mcp add claude-flow -- npx -y @claude-flow/cli@latest mcp start. For VS Code, add the same configuration to .vscode/mcp.json.

How do I repair a corrupted Ruflo memory database?

If the doctor reports warnings about .claude-flow/memory.db, delete the corrupted file with rm .claude-flow/memory.db and reinitialize using npx @claude-flow/cli@latest memory init --force. This recreates the hybrid SQLite + HNSW vector store required for Ruflo's context management.

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