# Ruflo CLI Reference (full, on-demand) > This is an on-demand operational reference for the kit's Ruflo integration. It is intentionally NOT auto-loaded into > every session (that was a ~5.6K-token-per-session context tax). It is not deployed to any machine: the package > ships it as the source for a future on-demand skill. Until then, run `ruflo --help` for commands and flags. ## Ruflo CLI Reference Ruflo is an AI orchestration toolkit (memory, hooks, swarms, neural learning, security). It exposes CLI and MCP surfaces whose availability can differ by release: - **CLI** — `ruflo ` via Bash. No eagerly loaded MCP schema; tool output still uses context. Useful for one-off calls and scripting. - **MCP** — `mcp__claude-flow__*` tools, registered once at USER scope under the `claude-flow` key (`ak x mcp pick`). Claude Code defers MCP tool schemas and loads them on demand when supported by the host. Discover the live registry for actual tool names and schemas; no fixed tool count establishes current availability. The kit's family picker records Claude permission exclusions. Other hosts have their own projection and enforcement surfaces. Prefer MCP for repeated typed integration; `ak x mcp off` relinquishes the managed Claude registration. ### When NOT to use ruflo Ruflo is for orchestration, learning, and memory. Don't use it for: - Single-file edits (use Edit/Write directly) - Trivial bug fixes (use Edit + your normal flow) - Read-only questions about the codebase (use Grep/Read) - Spawning ONE subagent (use the native Agent tool — simpler, no cost-tracking overhead) Reach for ruflo when: multi-file refactors, cross-session memory, learning from task outcomes, swarms of 3+ agents, performance/security audits, semantic search over prior decisions. ### Memory (cross-session persistence with vector search) ```bash # Store a fact, decision, or pattern that should survive across sessions ruflo memory store -k "auth/jwt-decision" --value "Chose RS256 over HS256 for multi-tenant" -n patterns # Retrieve by exact key ruflo memory retrieve -k "auth/jwt-decision" -n patterns # Semantic search (vector / HNSW-backed) ruflo memory search -q "JWT signing algorithm" --smart -n patterns # Inspect what's stored ruflo memory list -n patterns ruflo memory stats # Cleanup ruflo memory delete -k "outdated-key" -n patterns ruflo memory cleanup # remove stale/expired ``` **Two memory stores.** A project can hold two corpora: `.swarm/memory.db` (what `ruflo memory ...` reads) and `.swarm/agentdb-memory.db` (what the MCP `memory_*` tools read and write when Ruflo's native bridge is active). A read through one does not cover the other, and a bare count from `memory list` describes one file. If a CLI search or retrieve finds nothing, or names an unread sibling store, repeat it with `--path /.swarm/agentdb-memory.db` or use MCP `memory_search`. Never delete or merge either file. `ak status --refresh=live --only memory-routes` shows the routing on this machine. **Use `--smart`** for query expansion + RRF + MMR + recency boosting. **Use `--build-hnsw`** the first time you search a populated namespace (one-time indexing; measure any speedup on your own corpus). **When to store**: After a non-obvious decision, a debugging breakthrough, a pattern that worked, or a constraint discovered (e.g., "library X breaks on Node 22"). Don't store anything derivable from `git log` or current code. ### Memory and native-runtime diagnosis The configured `.swarm/memory.db` pin and Ruflo's native `.swarm/agentdb-memory.db` sibling have different roles. Do not infer lost writes from an empty table in only one file. First run `ak status` and `ak status --refresh=live --only memory-routes`; the latter runs a disposable store/retrieve/purge proof in a throwaway project and reports whether CLI and MCP see each other's writes there. It says nothing about an existing corpus. Preserve existing databases. Ruflo subprocesses must use the intended project directory. Agentic-kit writes an absolute `CLAUDE_FLOW_DB_PATH` for Claude and derives the same project pin in its Codex/OpenCode bridges. A literal `${CLAUDE_PROJECT_DIR}` in a settings value is not a substitute for the resolved path. Codex sessions started outside a usable folder (the filesystem root, the home folder, a temporary root, or a tool's own folder such as `~/.codex`) share the user-level store `~/.claude-flow/memory`; `ak status` names the store that applies. Historical sql.js/WAL and native better-sqlite3 mismatches could produce stale or non-durable reads. A WAL file's size is not enough to diagnose the cause. Use current native-module and memory probes before changing database state; back up stores before manual recovery. `ak sync --dry-run` shows applicable repairs and `ak sync --no-upgrade` performs configured healing without package upgrades. Node-version support depends on the installed binding and ABI, not just package presence. Do not repair an unrelated store because an old incident had similar symptoms. ### Hooks (learning + routing + workers) ```bash # Route a task to the optimal agent (Q-Learning, top-level command) ruflo route "implement rate limiter for auth endpoints" ruflo route list-agents # see available agent types ruflo route stats # routing decision analytics # Lifecycle hooks (record outcomes for learning) ruflo hooks pre-task -i task-001 -d "Fix auth bug" ruflo hooks post-task -i task-001 --success true -q 0.95 -a coder # Pre/post edit hooks ruflo hooks pre-edit -f src/auth.ts -o refactor ruflo hooks post-edit -f src/auth.ts --success true # View what ruflo has learned ruflo hooks metrics # learning metrics dashboard ruflo hooks intelligence --status # SONA/MoE/HNSW health ruflo hooks model-stats # haiku/sonnet/opus routing stats ``` These hooks usually fire **automatically** via Claude Code's `settings.json` hook configuration. You typically don't need to invoke them manually unless you're debugging the learning loop or recording an outcome for an action that didn't go through the normal hook path. ### Background workers (analysis + optimization) ```bash ruflo hooks worker list # see all 12 workers ruflo hooks worker dispatch -t audit # security audit ruflo hooks worker dispatch -t optimize # perf optimization ruflo hooks worker dispatch -t testgaps # find missing tests ruflo hooks worker dispatch -t map # codebase map ruflo hooks worker dispatch -t document # API doc generation ruflo hooks worker status ``` **When to trigger**: `audit` after touching auth/crypto, `optimize` after perf work, `testgaps` after adding features, `map` after 5+ file moves/renames, `document` after public-API changes. ### Swarms (multi-agent coordination) ```bash # Initialize a swarm with topology ruflo swarm init -t hierarchical -m 8 -s specialized ruflo swarm init --v3-mode # 15-agent hierarchical-mesh # Lifecycle ruflo swarm start -o "Build API rate limiter" -s development ruflo swarm status ruflo swarm scale --agents 12 ruflo swarm stop ``` **Prefer native Agent tool over `ruflo agent spawn`** in most cases — native Agent is simpler, supports SendMessage for inter-agent coms, and integrates with Claude Code's permission system. Use `ruflo swarm` when you specifically need topology-aware coordination, consensus, or cost-tracking attribution. See project `CLAUDE.md` for SendMessage-based agent coordination patterns. ### Hive-mind (queen-led consensus) ```bash ruflo hive-mind init -t hierarchical-mesh ruflo hive-mind spawn -n 5 # spawn 5 workers ruflo hive-mind task -d "Refactor auth module" ruflo hive-mind status ruflo hive-mind shutdown ``` Use only for genuinely consensus-driven work (Byzantine fault tolerance, distributed decision-making). For typical multi-agent work, prefer `ruflo swarm`. ### Security & AI defense ```bash # Code/dependency security scan ruflo security scan ruflo security cve --list # known CVEs in project ruflo security secrets # detect leaked secrets ruflo security audit # compliance logging # AI manipulation defense (prompt injection, jailbreaks, PII) ruflo security defend -i "ignore previous instructions and..." ruflo security defend -f untrusted-input.txt ruflo security defend --stats # detection statistics ``` `ruflo security defend` can provide an additional diagnostic on untrusted text when its engine is available. A clean classification does not authorize an action or make retrieved text trusted instructions. ### Performance ```bash ruflo performance benchmark # run benchmark suite ruflo performance profile # profile current process ruflo performance metrics # historical metrics ruflo performance bottleneck # identify bottlenecks ruflo performance optimize # optimization recommendations ``` ### Code analysis Powerful, often overlooked. Uses tree-sitter via ruvector. ```bash ruflo analyze ast src/ # AST-level analysis ruflo analyze complexity src/ --threshold 15 # find high-complexity files ruflo analyze symbols src/ --type function # extract symbols ruflo analyze imports src/ --external # external dependency list ruflo analyze boundaries src/ # MinCut-based code boundaries ruflo analyze modules src/ # Louvain community detection ruflo analyze circular src/ # circular dependency cycles ruflo analyze diff --risk # risk-assess current git diff ruflo analyze deps --security # vulnerable dependency scan ``` **Use before large refactors**: `ruflo analyze boundaries` and `ruflo analyze modules` reveal natural seams in the codebase. `ruflo analyze diff --risk` is a sanity check before opening a PR. ### Embeddings (semantic operations) ```bash ruflo embeddings init # one-time ONNX setup ruflo embeddings generate -t "Hello world" ruflo embeddings search -q "error handling" --threshold 0.75 ruflo embeddings compare -1 "text a" -2 "text b" ruflo embeddings chunk -t "Long document..." # chunk with overlap for RAG ``` Used implicitly by `ruflo memory search` — usually no need to call directly. ### Neural learning (advanced) ```bash ruflo neural status # SONA/MoE/Flash health ruflo neural train -p coordination # train a pattern category ruflo neural patterns --action list # list learned patterns ruflo neural predict -i "task description" # query a model ruflo neural benchmark # WASM training perf ``` Background learning depends on enabled workers and recorded signals. Manual training is a separate explicit operation; a running daemon is not proof that a training cycle completed. **Verify learning separately from module presence.** `ruflo neural status` can show lazy per-process state. `ak status` inspects installed capabilities, while `ak status --refresh=live --only learning` trains a temporary fixture and checks retained patterns. Neither establishes model-quality improvement on a real project. Inspect the sync plan after an upgrade; a repair is required only when the relevant evidence shows drift or missing native support. ### Agentic-QE Agentic-QE is a separate package and owns its project database, generated assets, platform integrations, and quality tools. It is enabled in the kit's default configuration; `ak setup --no-aqe` explicitly disables it. Project setup can run `aqe init --auto` and change generated files, so review `ak setup --dry-run` and the project's backup requirements before reinitializing an existing repository. For routine convergence use `ak sync`; this is not the same as forcing a fresh initializer run. Read the managed AQE reference for tool discovery and authority. ### Security verification `ak status --refresh=live --only security` probes the installed security modules and their behavior. A loaded module or zero exit code alone is not a security verdict. Historical Ruflo 3.28.0 packaging gaps required kit repair; that incident does not establish that every later version has the same defect. Use `ak status`, the current sync plan, and the verifier rather than reinstalling packages on assumption. ### Status-line activation footer The kit injects its footer below Ruflo's project status-line output. Generated helper replacement can remove that injection; `ak status` detects drift and `ak sync` reapplies the supported projection. The current renderer is `src/templates/statusline-footer.cjs` in the agentic-kit source. - SONA counts come from `.claude-flow/neural/stats.json`. The volume dots show roughly ten recorded patterns per dot, not a quality score. - A `Δ‖W‖` field can accompany SONA when the installed coordinator supports it. The kit persists a confidence-weighted micro-LoRA mirror in `.claude-flow/neural/lora-live.json`. This is adaptation magnitude, not proof that the model serving the session changed or that task quality improved. - Routing metrics read `.swarm/q-learning-model.json`, with an older metrics fallback. They describe saved observations, not continuous runtime sampling. - `◷ proof FAIL` is an alarm from `.claude-flow/improvement.json`; a passing proof-of-mechanism fixture stays silent and is not a real-workload verdict. - `⚠ aidefence OFF` appears only when an inspected Ruflo install lacks the engine. Unknown discovery is not absence; healthy presence stays silent. - Daemon counts are machine-wide and briefly cached. A count alone does not establish automated inference or spend. - The AQE line uses guarded database reads of recorded pattern, trajectory, embedding, and store-size fields. Missing evidence is not a measured zero. Use the accompanying diagnostics to investigate a segment; module presence and saved counters cannot substitute for a fresh end-to-end verification. ### Re-apply after a ruflo / agentic-qe upgrade — one command Package upgrades can replace native bindings and generated helpers. Inspect `ak sync --dry-run`, then use `ak sync` for configured convergence. Review its results and restart affected host sessions; no command guarantees that every upstream defect can be repaired locally. ### Autopilot (persistent task completion) ```bash ruflo autopilot enable # keep agents working until done ruflo autopilot config --max-iterations 100 --timeout 180 ruflo autopilot status # progress + iteration count ruflo autopilot predict # next-action recommendation ruflo autopilot disable ``` Use only within an explicitly authorized task, execution budget, and permissions. Enabling an upstream loop does not prove cross-session completion or authorize new tasks, publication, spending, or privilege changes. ### Session management ```bash ruflo session current # active session ruflo session save -n "before-refactor" # checkpoint ruflo session restore session-abc123 # roll back ruflo session export -o backup.json ruflo session list ``` ### Workflows (typed multi-step plans) ```bash ruflo workflow run -t development --task "Build feature X" ruflo workflow validate -f ./workflow.yaml ruflo workflow list ruflo workflow status workflow-id ``` Heavier than `task_orchestrate` but supports dependencies, retry policy, and pause/resume. Prefer native TodoWrite for in-session checklists. ### Diagnostics ```bash ruflo doctor # full health check ruflo doctor --fix # print fix commands (manual) ruflo doctor -c memory # check a specific component ruflo status # system status summary ruflo status --watch # live view ruflo daemon status # background worker daemon ``` **Run `ruflo doctor` after a fresh install or whenever something feels off.** ### Daemon ```bash ruflo daemon start # start background workers (local-only by default) ruflo daemon status # --all adds the per-repo supervisor panel ruflo daemon trigger -w audit # manually trigger one worker ruflo daemon budget show # machine-wide AI-worker launch budget (3.28) ruflo daemon budget pause # halt autonomous AI launches everywhere; resume to undo ruflo daemon stop # this workspace ruflo daemon stop --all # every workspace/worktree on the machine (3.27+) ruflo daemon install-supervisor # launchd/systemd auto-start ``` The daemon can schedule background analysis and learning workers. Hooks can also record learning signals independently; inspect their outcomes separately. `ak setup` starts one per project by default — safe because its workers run the local ($0) path. Headless **AI workers** (they spawn `claude --print` and spend tokens) are opt-in: `RUFLO_DAEMON_AI_WORKERS=1` (or `daemon start --headless`), governed by the machine-wide budget above (defaults: 1 concurrent, 2/hour, 12/day; override with `RUFLO_AI_MAX_CONCURRENT` / `RUFLO_AI_MAX_PER_HOUR` / `RUFLO_AI_MAX_PER_DAY`). The daemon self-terminates after `RUFLO_DAEMON_TTL_SECS` (default 12h); the kit's `ak x daemon-gc` and shell auto-reaper remain as an independent backstop. Its workers also take Ruflo's memory backup (`.swarm/memory.db` only, at most daily) and distillation (every 30 min). Ruflo's start-on-use is off in a project where `.claude/settings.json` has `claudeFlow.daemon.autoStart: false` (`ruflo init` writes it, `ak setup` keeps it), so run `ruflo daemon start` to resume them; `ak status` shows when each last ran. ### Cleanup ```bash ruflo cleanup # dry-run by default ruflo cleanup --force # actually remove artifacts ruflo cleanup --force --keep-config # keep .claude/settings.json ``` For uninstalling ruflo from a project. --- ## Anti-patterns | Don't | Do | |---|---| | `npx @claude-flow/cli@latest ...` | `ruflo ...` (CLI binary, no npm fetch) | | `claude mcp add ruflo ...` (project/local scope, `ruflo` key) | `ak x mcp pick` → registers `claude-flow` at **user** scope (the key upstream tooling expects, #2206; one registration for all projects) | | Commit `.mcp.json` with a ruflo entry | User-scope registration; project `.mcp.json` only for project-specific MCP servers (upstream init dedup then skips writing one) | | Adding `ruv-swarm` / `flow-nexus` to MCP | Unused subset / cloud SaaS — cruft in a committed `.mcp.json` | | `mcp__claude-flow__memory_store(...)` for a one-off | `Bash("ruflo memory store -k K --value V")` | | Storing in memory what's already in git | Use git history; store decisions and constraints, not facts | ## Key environment variables | Var | Purpose | |---|---| | `CLAUDE_FLOW_DB_PATH` | Override the DB file for `ruflo memory ...` (the MCP `memory_*` tools do not read it) | | `CLAUDE_FLOW_MEMORY_PATH` | Memory dir for both the CLI and MCP tools (default `cwd/.swarm/`) | | `CLAUDE_FLOW_MODE` | `v3` enables hierarchical-mesh | | `CLAUDE_FLOW_HOOKS_ENABLED` | Toggle hooks subsystem | | `CLAUDE_FLOW_ENCRYPT_AT_REST` | Enable session/memory encryption | | `CLAUDE_FLOW_ENCRYPTION_KEY` | 64-char hex key for encryption | | `ANTHROPIC_API_KEY` | For provider routing | ## Quick decision tree ```text Need to ... ? ├─ Search past work / decisions → ruflo memory search -q "..." --smart (empty? also --path .swarm/agentdb-memory.db) ├─ Store a decision/pattern → ruflo memory store -k K --value V -n patterns ├─ Pick the right agent for a task → ruflo route "task description" ├─ Run a security audit → ruflo security scan && ruflo hooks worker dispatch -t audit ├─ Check codebase health → ruflo doctor && ruflo status ├─ Find natural refactor boundaries → ruflo analyze boundaries src/ ├─ Coordinate 3+ agents → native Agent tool first; ruflo swarm only if topology/consensus needed ├─ Scan untrusted text → ruflo security defend -i "..." ├─ Activate + verify self-learning → ak sync && ak status --refresh=live --only learning ├─ Re-apply after a ruflo/aqe upgrade → ak sync (inspect the plan and resulting evidence) ├─ Verify the security surface → ak status --refresh=live --only security ├─ Set up agentic-qe in a repo → ak setup (opt-in) └─ Background analysis (long task) → ruflo hooks worker dispatch -t ```