Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ruvnet/ruflo/llms.txt

Use this file to discover all available pages before exploring further.

ruflo init is the first command you run in any new project. It creates the .claude/ directory tree (settings, skills, commands, agents, helpers), writes .mcp.json for Claude Code MCP integration, and optionally bootstraps the V3 runtime in .claude-flow/. Run it once to set up, and use init upgrade whenever you update Ruflo to pull in new helpers without wiping your data.

​
Synopsis

ruflo init [subcommand] [options]

​
Subcommands

SubcommandDescription
(default)Run standard initialization with default, minimal, or full profile
wizardInteractive step-by-step setup with prompts for every setting
checkVerify whether Ruflo is already initialized in the current directory
skillsInstall or update only the skills in .claude/skills/
hooksCreate or overwrite only the hooks configuration in settings.json
upgradeUpdate helpers and statusline while preserving existing data

​
Default init

Bootstraps a new project using the default profile (recommended for most teams). 
ruflo init [options]
Ruflo detects prior initialization by checking for a claudeFlow section in .claude/settings.json, a claude-flow or ruflo key in .mcp.json, or the presence of .claude-flow/config.yaml. If any of these signals are found, the command warns and prompts before overwriting (or exits non-zero in non-interactive mode).

​
What gets created

.claude/
├── settings.json        ← Claude Code hook configuration
├── CLAUDE.md            ← Swarm guidance & project instructions
├── skills/              ← Slash-command skill library (130+ skills)
├── commands/            ← Custom Claude Code commands
├── agents/              ← Agent role definitions
└── helpers/
    └── hook-handler.cjs ← Hook dispatch script (required by all hooks)

.mcp.json                ← MCP server registration for Claude Code
.claude-flow/
├── config.yaml          ← V3 runtime configuration
├── data/                ← Persistent data (preserved on upgrade)
├── logs/                ← Runtime logs
└── sessions/            ← Session snapshots

​
Options

​
--force
boolean
default:"false"
Overwrite existing configuration without prompting.
​
--minimal / -m
boolean
default:"false"
Create a minimal configuration: core skills only, no commands, no agent definitions. Fastest install (~15 s with --omit=optional).
​
--full
boolean
default:"false"
Create a full configuration: all skill sets, all agent types, all hooks enabled. Excludes auth-gated cloud MCP servers unless --cloud-mcp is also passed.
​
--cloud-mcp
boolean
default:"false"
Register the auth-gated cloud MCP servers (ruv-swarm, flow-nexus) in .mcp.json. Only meaningful with --full.
​
--codex
boolean
default:"false"
Initialize for OpenAI Codex CLI: creates AGENTS.md and .agents/skills/ instead of CLAUDE.md and .claude/skills/.
​
--dual
boolean
default:"false"
Dual-mode: initialize for both Claude Code and OpenAI Codex simultaneously.
​
--all-agents
boolean
default:"false"
Install all ~89 agent categories. Default is the ~24-agent substrate (core, consensus, swarm, SPARC, testing).
​
--skip-claude
boolean
default:"false"
Skip .claude/ directory creation; set up V3 runtime only.
​
--only-claude
boolean
default:"false"
Create only the .claude/ directory; skip V3 runtime setup.
​
--no-global
boolean
default:"false"
Skip writing the Ruflo Integration pointer block into ~/.claude/CLAUDE.md.
​
--start-all
boolean
default:"false"
Auto-start the background daemon, initialize the memory database, and create an initial swarm after init completes.
​
--start-daemon
boolean
default:"false"
Auto-start only the background daemon after init.
​
--with-embeddings
boolean
default:"false"
Initialize the ONNX embedding subsystem with Poincaré hyperbolic support.
​
--embedding-model
string
default:"Xenova/all-MiniLM-L6-v2"
ONNX model to use for embeddings. Choices: Xenova/all-MiniLM-L6-v2 (384-dim, fast), Xenova/all-mpnet-base-v2 (768-dim, higher quality).

​
wizard

The interactive setup wizard walks you through every configuration decision: component selection, topology, memory backend, embedding model, and hook set. Answers are gathered before any files are written. 
ruflo init wizard
The wizard presents these choices in order:
  1. Preset — default, minimal, full, or custom
  2. Components (custom only) — checkboxes for each .claude/ subdirectory
  3. Skill sets — core, agentdb, github, v3, flowNexus
  4. Hooks — per-event toggles
  5. Swarm topology — hierarchical-mesh, mesh, hierarchical, adaptive
  6. Max agents — numeric input (1–50)
  7. Memory backend — hybrid, agentdb, sqlite, in-memory
  8. HNSW indexing — enable/disable
  9. Neural learning — enable/disable (includes LearningBridge + Knowledge Graph)
  10. Embedding model — model selection

​
check

Inspect whether the current directory is already initialized. 
ruflo init check [--format json]
Exits 0 with a success message if initialized; exits non-zero if not. Pass --format json for machine-readable output.

​
skills

Install or refresh only the skill files in .claude/skills/, leaving all other configuration untouched. 
ruflo init skills [--all] [--core] [--agentdb] [--github] [--v3]
​
--all
boolean
default:"false"
Install every available skill set.
​
--core
boolean
default:"true"
Install core skills: swarm, memory, SPARC patterns.
​
--agentdb
boolean
default:"false"
Install AgentDB vector-database skills.
​
--github
boolean
default:"false"
Install GitHub integration skills (PR, issues, workflow automation).
​
--v3
boolean
default:"false"
Install V3 implementation skills.

​
hooks

Create or overwrite only the hooks block in .claude/settings.json. Also writes .claude/helpers/hook-handler.cjs (the hook-handler script is required; omitting it silently produces a settings file with no hooks key). 
ruflo init hooks [--minimal]
​
--minimal
boolean
default:"false"
Enable only PreToolUse and PostToolUse hooks. Default enables all seven hook events.

​
upgrade

Pulls in the latest hook-handler.cjs and statusline helper without touching your stored memories, patterns, or custom skills. 
ruflo init upgrade [--add-missing] [--settings] [--verbose]
​
--add-missing / -a
boolean
default:"false"
Detect and install any new skills, agents, and commands added since your last install.
​
--settings / -s
boolean
default:"false"
Merge new settings (Agent Teams configuration, new hook entries) into the existing settings.json.
​
--verbose / -v
boolean
default:"false"
Print the full list of preserved files alongside updated and created ones.

​
Examples

# Default initialization — recommended for new projects
ruflo init
Running ruflo init in a project that already has .claude/settings.json created by Claude Code itself will not trigger the “already initialized” warning — Ruflo only considers a project initialized when it finds Ruflo-specific signals (a claudeFlow section, a claude-flow/ruflo key in .mcp.json, or .claude-flow/config.yaml).
After initializing, run ruflo metaharness score for a five-dimension harness readiness scorecard to verify the project is wired up correctly.

Build docs developers (and LLMs) love

Get started for freeTalk to us