MoFlo

A standalone, opinionated AI agent orchestration toolkit for Claude Code, optimized for local development.

TL;DR

MoFlo makes your AI coding assistant remember what it learns, check what it knows before exploring files, and get smarter over time — all automatically. Install it, run flo init, restart your AI client, and everything just works: your docs and code are indexed on session start so the AI can search them instantly, gates prevent the AI from wasting tokens on blind exploration, task outcomes feed back into routing so it picks the right agent type next time, and context depletion warnings tell you when to start a fresh session. No configuration, no API keys, no cloud services — it all runs locally on your machine.

Quickstart

npm install --save-dev moflo
flo init

Restart Claude Code (or your MCP client). That's it — memory, indexing, gates, and routing are all active.

Or — just ask Claude to install MoFlo into your project and initialize it!

To verify everything is running, ask Claude to run flo healer with full diagnostics after restarting. If anything fails, ask Claude to fix it with flo healer --fix. (flo doctor is still accepted as an alias.)

Opinionated Defaults

MoFlo makes deliberate choices so you don't have to:

• Fully self-contained — No external services, no cloud dependencies, no API keys. Everything runs locally on your machine.
• Minimal dependencies — small runtime dep set, all WASM or prebuilt binaries. No native compilation, no node-gyp, no platform-specific build steps.
• Node.js runtime — Targets Node.js specifically. All scripts, hooks, and tooling are JavaScript/TypeScript. No Python, no Rust binaries, no native compilation.
• sql.js (WASM) — The memory database uses sql.js, a pure WebAssembly build of SQLite. No native better-sqlite3 bindings to compile, no platform-specific build steps. Works identically on Windows, macOS, and Linux.
• Neural embeddings by default — 384-dimensional embeddings using all-MiniLM-L6-v2. No hash fallback, no peer-optional setup, no install prompts — real semantic search works out of the box. A postinstall step trims the embedding runtime to your platform and strips GPU-only libraries the runtime never loads, reclaiming roughly 340 MB on Linux and 150 MB on Windows from a fresh install. Set MOFLO_NO_PRUNE=1 to skip the trim, or ONNXRUNTIME_NODE_INSTALL_CUDA=true to keep CUDA GPU support.
• Full learning stack wired up OOTB — All configured and functional from flo init, no manual setup:
  • SONA (Self-Optimizing Neural Architecture) — learns from task trajectories
  • MicroLoRA — fast rank-2 weight adaptations (~1µs per adapt)
  • EWC++ (Elastic Weight Consolidation) — prevents catastrophic forgetting across sessions
  • HNSW Vector Search — fast nearest-neighbor search over your knowledge base
  • Semantic Routing — maps tasks to the right agent via learned patterns (ReasoningBank)
  • Trajectory Persistence — outcomes survive across sessions
  • All local, no GPU, no API keys, no external services.
• Memory-first — Claude must search what it already knows before exploring files. Enforced by hooks, not just instructions.
• Task registration before agents — Sub-agents can't spawn until work is tracked. Prevents runaway agent proliferation.
• Learned routing — Task outcomes feed back into the routing system automatically. No manual configuration needed — it gets smarter with use.
• Incremental indexing — Guidance and code map indexes run on every session start but skip unchanged files. Fast after the first run.
• Built for Claude Code, works with others — We develop and test exclusively with Claude Code. The MCP tools, memory system, and hooks are client-independent and should work with any MCP-capable AI client, but Claude Code is the only tested target.
• GitHub-oriented — The /flo skill, PR automation, and issue tracking are built around GitHub. With Claude's help, you can adapt them to your own issue tracker and source control system.
• Cross-platform — Works identically on macOS, Linux, and Windows.

Features

Feature	What It Does
Semantic Memory	384-dim domain-aware embeddings. Store knowledge, search it instantly.
Code Navigation	Indexes your codebase structure so Claude can answer "where does X live?" without Glob/Grep.
Guidance Indexing	Chunks your project docs (.claude/guidance/, docs/) and makes them searchable.
Gates	Enforces memory-first and task-creation patterns via Claude Code hooks. Prevents Claude from skipping steps.
Learned Routing	Routes tasks to the right agent type. Learns from outcomes — gets better over time.
Spell Engine	Define multi-step automations as YAML — shell commands, agent spawns, conditionals, loops, memory ops. Full documentation →
/flo Skill	Execute GitHub issues through a full process: research → enhance → implement → test → simplify → PR. (Also available as /fl.)
Context Tracking	Monitors context window usage (FRESH → MODERATE → DEPLETED → CRITICAL) and advises accordingly.
Cross-Platform	Works on macOS, Linux, and Windows.

Getting Started

1. Install and init

npm install --save-dev moflo
flo init

flo init automatically scans your project to find where your guidance, code, and tests live, then writes the results into moflo.yaml. It looks for:

What	Directories it checks	Default if none found
Guidance	.claude/guidance, docs/guides, docs, architecture, adr, .cursor/rules	.claude/guidance
Source code	src, packages, lib, app, apps, services, server, client	src
Tests	tests, test, __tests__, spec, e2e, plus __tests__ dirs inside src/	tests
Languages	Scans detected source dirs for file extensions	.ts, .tsx, .js, .jsx

It also generates:

Generated File	Purpose
moflo.yaml	Project config with detected guidance/code locations
.claude/settings.json	Gate hooks for Claude Code
.claude/skills/flo/	The /flo issue execution skill (also /fl)
CLAUDE.md section	Teaches Claude how to use MoFlo
.gitignore entries	Excludes MoFlo state directories

In interactive mode (flo init without --yes), it shows what it found and lets you confirm or adjust before writing.

Migrating from Claude Flow / Ruflo

If flo init detects an existing .claude/settings.json or .claude-flow/ directory (from a prior Claude Flow or Ruflo installation), it treats the project as already initialized and runs in update mode — merging MoFlo's hooks and configuration into your existing setup without overwriting your data. Specifically:

• Hooks — If your .claude/settings.json already has MoFlo-style gate hooks (flo gate), the hooks step is skipped. Otherwise, MoFlo's hooks are written into the file (existing non-MoFlo hooks are not removed).
• MCP servers — MoFlo registers itself as the moflo server in .mcp.json. If you had claude-flow or ruflo MCP servers configured previously, those entries remain untouched — you can remove them manually once you've verified MoFlo is working. The flo healer command checks for the moflo server specifically.
• Config files — moflo.yaml, CLAUDE.md, and .claude/skills/flo/ follow the same skip-if-exists logic. Use --force to regenerate them.

To force a clean re-initialization over an existing setup:

flo init --force

2. Review your guidance and code settings

Open moflo.yaml to see what init detected. The two key sections:

Guidance — documentation that helps Claude understand your project (conventions, architecture, domain context):

guidance:
  directories:
    - .claude/guidance    # project rules, patterns, conventions
    - docs                # general documentation

Code map — source files to index for "where does X live?" navigation:

code_map:
  directories:
    - src                 # your source code
    - packages            # shared packages (monorepo)
  extensions: [".ts", ".tsx"]
  exclude: [node_modules, dist, .next, coverage]

Tests — test files to index for "what tests cover X?" reverse mapping:

tests:
  directories:
    - tests               # your test files
    - __tests__            # jest-style test dirs
  patterns: ["*.test.*", "*.spec.*", "*.test-*"]
  extensions: [".ts", ".tsx", ".js", ".jsx"]
  exclude: [node_modules, coverage, dist]
  namespace: tests

MoFlo chunks your guidance files into semantic embeddings, indexes your code structure, and maps test files back to their source targets — so Claude searches your knowledge base before touching any files. Adjust these directories to match your project:

# Monorepo with shared docs
guidance:
  directories: [.claude/guidance, docs, packages/shared/docs]
code_map:
  directories: [packages, apps, libs]

# Backend + frontend
code_map:
  directories: [server/src, client/src]

3. Index and verify

flo memory index-guidance    # Index your guidance docs
flo memory code-map          # Index your code structure
flo healer                   # Verify everything works (alias: flo doctor)

Both indexes run automatically at session start after this, so you only need to run them manually on first setup or after major structural changes. The first index may take a minute or two on large codebases (1,000+ files) but runs in the background — you can start working immediately. Subsequent indexes are incremental and typically finish in under a second. To reindex everything at once:

flo memory refresh           # Reindex all content, rebuild embeddings, cleanup, vacuum

Auto-Indexing

MoFlo automatically indexes three types of content on every session start, so your AI assistant always has up-to-date knowledge without manual intervention.

What gets indexed

Index	Content	What it produces	Namespace
Guidance	Markdown files in your guidance directories (.claude/guidance/, docs/, etc.)	Chunked text with 384-dim semantic embeddings — enables natural-language search across your project documentation	guidance
Code map	Source files in your code directories (src/, packages/, etc.)	Structural index of exports, classes, functions, and types — enables "where does X live?" navigation without Glob/Grep	code-map
Tests	Test files matching configured patterns (*.test.*, *.spec.*)	Reverse mapping from test files to their source targets — enables "what tests cover X?" lookups	tests

How it works

1. Session start hook — When your AI client starts a new session, MoFlo's SessionStart hook launches the indexers sequentially in a single background process. This runs silently — you can start working immediately.
2. Incremental — Each indexer tracks file modification times. Only files that changed since the last index run are re-processed. The first run on a large codebase may take a minute or two; subsequent runs typically finish in under a second.
3. Embedding generation — Guidance chunks are embedded using MiniLM-L6-v2 (384 dimensions, WASM). These vectors are stored in the SQLite memory database and used for semantic search.
4. No blocking — The indexers run in the background and don't block your session from starting. You can begin working immediately.

Configuration

Each indexer can be toggled independently in moflo.yaml:

auto_index:
  guidance: true     # Index docs on session start
  code_map: true     # Index code structure on session start
  tests: true        # Index test files on session start

Set any to false to disable that indexer. The underlying data remains in memory — you just stop refreshing it automatically. You can still run indexers manually:

flo memory index-guidance    # Manual guidance reindex
flo memory code-map          # Manual code map reindex
flo memory refresh           # Reindex everything + rebuild embeddings + vacuum

Why this matters

Without auto-indexing, your AI assistant starts every session with a blank slate — it doesn't know what documentation exists, where code lives, or what tests cover which files. It resorts to Glob/Grep exploration, which burns tokens and context window on rediscovery.

With auto-indexing, the AI can search semantically ("how does auth work?") and get relevant documentation chunks ranked by similarity, or ask "where is the user model defined?" and get a direct answer from the code map — all without touching the filesystem.

The Gate System

MoFlo installs Claude Code hooks that run on every tool call. Together, these gates create a feedback loop that prevents Claude from wasting tokens on blind exploration and ensures it builds on prior knowledge.

Gates explained

Gate	What it enforces	When it triggers	Why it matters
Memory-first	Claude must search the memory database before using Glob, Grep, or Read on guidance files	Before every Glob/Grep call, and before Read calls targeting .claude/guidance/	Prevents the AI from re-exploring files it (or a previous session) already indexed. Forces it to check what it knows first, saving tokens and context window.
TaskCreate-first	Claude must call TaskCreate before spawning sub-agents via the Task tool	Before every Task (agent spawn) call	Ensures every piece of delegated work is tracked. Prevents runaway agent proliferation where Claude spawns agents without a clear plan.
Context tracking	Tracks conversation length and warns about context depletion	On every user prompt (UserPromptSubmit hook)	As conversations grow, AI quality degrades. MoFlo tracks interaction count and assigns a bracket (FRESH → MODERATE → DEPLETED → CRITICAL), advising Claude to checkpoint progress or start a fresh session before quality drops.
Routing	Analyzes each prompt and recommends the optimal agent type and model tier	On every user prompt (UserPromptSubmit hook)	Saves cost by suggesting haiku for simple tasks, sonnet for moderate ones, opus for complex reasoning — without you having to think about model selection.

Smart classification

The memory-first gate doesn't blindly block every request. It classifies each prompt:

• Simple directives (e.g., "commit", "yes", "continue", "looks good") — skip the gate entirely, no memory search required
• Task-oriented prompts (e.g., "fix the auth bug", "add pagination to the API") — gate enforced, must search memory first

Escape hatch

Prefix any prompt with @@ to bypass the memory-first gate for that turn. Useful for conversational questions, thinking out loud, or discussions that don't need prior context:

@@ what do you think about this approach?
@@ question — is there a better way to handle auth tokens?

The @@ prefix is stripped before Claude sees the prompt, so it won't affect the response.

Disabling gates

All gates are configurable in moflo.yaml:

gates:
  memory_first: true          # Set to false to disable memory-first enforcement
  task_create_first: true     # Set to false to disable TaskCreate enforcement
  context_tracking: true      # Set to false to disable context bracket warnings

You can also disable individual hooks in .claude/settings.json by removing the corresponding hook entries.

The /flo Skill

Inside your AI client, the /flo (or /fl) slash command drives GitHub issue execution:

/flo <issue>                  # Full process (research → implement → test → PR)
/flo -t <issue>               # Ticket only (research and update ticket, then stop)
/flo -r <issue>               # Research only (analyze issue, output findings)
/flo -s <issue>               # Swarm mode (multi-agent coordination)
/flo -h <issue>               # Hive-mind mode (consensus-based coordination)
/flo -n <issue>               # Normal mode (default, single agent, no swarm)

For full options and details, type /flo with no arguments — your AI client will display the complete skill documentation. Also available as /fl.

Epic handling

When you pass an issue number, /flo automatically checks if it's an epic — no extra flag needed. An issue is treated as an epic if any of these are true:

• It has a label matching epic, tracking, parent, or umbrella (case-insensitive)
• Its body contains a ## Stories or ## Tasks section
• Its body has checklist-linked issues: - [ ] #101
• Its body has numbered issue references: 1. #101
• The issue has GitHub sub-issues (via the API)

When an epic is detected, /flo processes each child story sequentially — full process per story (research → implement → test → PR), one at a time, in the order listed.

For simple epics with independent stories, /flo <epic> is all you need. For complex features where you want state tracking, resume capability, and auto-merge between stories, use flo epic instead.

Feature Orchestration (flo epic)

flo epic is the robust epic runner — it adds persistent state, resume from failure, and per-story auto-merge on top of /flo. It takes a GitHub epic issue number:

flo epic 42                                # Fetch epic #42, run all stories sequentially
flo epic 42 --dry-run                      # Preview execution plan without running
flo epic 42 --strategy auto-merge          # Per-story PRs with auto-merge between stories
flo epic status 42                         # Check progress (which stories passed/failed)
flo epic reset 42                          # Reset state for re-run

flo epic fetches the epic from GitHub, extracts child stories from checklists, numbered references, and ## Stories / ## Tasks sections, then runs each through /flo with state tracking. If a story fails, you can fix the issue and re-run flo epic 42 — it resumes from where it left off, skipping already-passed stories. (flo epic run 42 is an explicit alias for the same shorthand.)

	/flo <epic>	flo epic <epic>
State tracking	No	Yes (epic-state memory namespace)
Resume from failure	No	Yes (skips passed stories)
Auto-merge PRs	No	Yes (--strategy auto-merge)
Dry-run preview	No	Yes

Spells

What are spells?

Spells are declarative YAML automations composed of pluggable step commands. They exist because shell scripts drift, ad-hoc prompts aren't reproducible, and CI/CD pipelines are the wrong tool for local automation. A spell is deterministic (same inputs → same steps), reviewable (a YAML file you read like a recipe), and replayable (re-cast it tomorrow and it behaves the same). Spells run from the CLI (flo spell cast), from an MCP tool call inside your AI client, or on a schedule.

How do they work?

Each cast goes through the same lifecycle:

1. Parse & validate — YAML is parsed and every step's config is checked against its command's schema.
2. Resolve capabilities — every step declares what it needs (shell, net, fs:read, fs:write, memory, credentials, browser, agent). Undeclared access is rejected before execution.
3. Execute the step graph — steps run sequentially by default, or in parallel groups, with depends_on for ordering and condition/loop for flow control.
4. Outputs flow forward — any step can reference a prior step's output as {stepId.field}, so later steps can consume earlier results.
5. Persistence — memory writes, artifacts, and per-step logs persist between runs; pause/resume and dry-run are supported.

flo spell cast -n development            # Cast a named spell
flo spell cast -f ./my-spell.yaml        # Cast from a file
flo spell cast -n sa --dry-run           # Validate without casting
flo spell list                           # List available spells and recent runs
flo spell grimoire list                  # Browse built-in spell templates
flo spell schedule list                  # List scheduled spells

Defining spells

name: my-spell
steps:
  - name: lint
    command: npm run lint
  - name: test
    command: npm test
  - name: deploy
    command: ./deploy.sh
    depends_on: [lint, test]

Steps support shell (bash), agent spawns, memory reads/writes, conditionals, loops, parallel groups, browser automation, GitHub/IMAP/Outlook/Slack/MCP integrations, prompts, waits, graphs, and composite steps. See docs/SPELLS.md for the full schema.

Sandboxing and security

Spells run with least-privilege access. Each step command declares the capabilities it needs (shell, net, fs:read, fs:write, memory, credentials, browser, browser:evaluate, agent), and the runner blocks any undeclared access. Spell authors can further restrict capabilities per step — e.g. fs:read: ["./config/"] or shell: ["cat", "jq"] — but never expand them.

Bash steps also run inside an OS sandbox when one is available. MoFlo auto-selects the best tier installed on your machine:

Tier	Platform	Isolation
Docker	all	Container, strictest
bwrap	Linux	User namespaces
sandbox-exec	macOS	Apple seatbelt profile
none	fallback	Capability-only enforcement

The sandbox is network-off by default; a step must explicitly declare net to reach the outside world. Credentials referenced as {credentials.X} are resolved from the encrypted credential store, masked in logs, and never written to disk. A destructive-pattern checker refuses to run bash commands that look like rm -rf /, unscoped git push --force, and similar footguns. See docs/SPELL-SANDBOXING.md for the full model.

Reusability

You interact with spells at three tiers:

1. Shipped spells — bundled with MoFlo and ready to cast. Browse them with flo spell grimoire list.
2. User spells — YAML files you drop in .claude/spells/. Override the location in moflo.yaml:

   spells:
     userDirs:
       - .claude/spells
       - my/project/spells

   A user spell with the same name as a shipped one wins — that's how you customize a shipped spell without forking.
3. Custom step commands and connectors — drop TypeScript/JavaScript files in .claude/spells/steps/ (new step types) and .claude/spells/connectors/ (new connectors). They're auto-discovered at startup. Connectors that wrap heavy SDKs (IMAP, MCP) declare those SDKs as optionalDependencies; install them only if your spells use them.

Scheduling

Spells can run on a schedule. The MoFlo background daemon polls for due spells once a minute and casts them — no external cron, no extra services.

Three timing options:

# Cron (5 fields: minute hour day-of-month month day-of-week)
flo spell schedule create -n nightly-audit --cron "0 2 * * *"

# Interval (e.g., 90s, 30m, 6h, 1d)
flo spell schedule create -n health-check --interval 30m

# One-time (ISO 8601 datetime)
flo spell schedule create -n migration --at 2026-04-15T09:00:00Z

You can also declare a schedule directly inside the spell YAML — that registers it on every daemon start:

name: nightly-audit
schedule:
  cron: "0 2 * * *"
steps:
  - id: audit
    type: bash
    config:
      command: ./scripts/audit.sh

Daemon prerequisite. Schedules only fire while the daemon is running. To survive reboot:

flo daemon install   # registers an OS-level autostart service
flo daemon status    # shows whether the service is registered AND running

flo spell schedule create warns when the daemon isn't installed so you don't quietly miss runs.

Monitoring. The Luminarium (the moflo daemon's localhost UI) surfaces live schedules, recent executions, and per-schedule controls (disable / re-enable / run now). It starts alongside the daemon at http://localhost:3117 (override with --dashboard-port or disable with --no-dashboard).

For full configuration (scheduler: block in moflo.yaml), event types, and the catch-up window after restarts, see docs/SPELLS.md#scheduling.

Building spells with the /spell-builder skill

Inside your AI client, use the /spell-builder skill to create, edit, and validate spell definitions interactively. The skill understands the full spell schema and available step commands, so you can describe what you want in natural language and it will generate the YAML:

/spell-builder                           # Start the spell builder

Other AI-client skills shipped with MoFlo

Beyond /flo, /spell-builder, and /eldar, MoFlo ships a handful of focused slash-command skills that work in any consumer project once you flo init:

Skill	Purpose
/guidance	Author and audit guidance docs in .claude/guidance/. Default mode walks you through one doc; /guidance -a audits every doc against the universal guidance rules (Purpose lines, See Also, line counts, hedged language).
/simplify	Adaptive code review on the current diff. Tier-based fan-out — trivial edits get a self-review, small diffs get one routed agent, cross-cutting refactors get three parallel agents. Routes through the moflo model router for cost-aware execution.
/spell-schedule	Schedule a spell on the local moflo daemon (cron, interval, or one-time) without leaving the chat. For remote Anthropic-cloud agents on a schedule, use Claude Code's built-in /schedule instead.

Run any of them with no arguments to see full usage, or browse the source in .claude/skills/ (each skill is a single SKILL.md file).

Epics

Epics are a specialized process for handling GitHub issues that contain multiple child stories. When you pass a GitHub issue to /flo and it's detected as an epic, MoFlo processes each child story sequentially through the full /flo process (research → implement → test → PR).

For simple epics, /flo <epic-number> is all you need. For complex features requiring state tracking, resume from failure, and auto-merge between stories, use the dedicated flo epic command:

flo epic 42                              # Run all stories in epic #42
flo epic 42 --strategy auto-merge        # Per-story PRs with auto-merge
flo epic 42 --dry-run                    # Preview execution plan
flo epic status 42                       # Check progress
flo epic reset 42                        # Reset state for re-run

See the Epic handling section above for detection criteria and the comparison between /flo <epic> and flo epic run.

Commands

You don't need to run these for normal use — flo init sets everything up, and the hooks handle memory, routing, and learning automatically. These commands are here for manual setup, debugging, and tweaking.

Memory

flo memory store -k "key" --value "data"    # Store with 384-dim embedding
flo memory search -q "auth patterns"         # Semantic search
flo memory index-guidance                    # Index guidance docs
flo memory code-map                          # Index code structure
flo memory rebuild-index                     # Regenerate all embeddings
flo memory refresh                           # Reindex all + rebuild + cleanup + vacuum
flo memory stats                             # Show statistics

Routing & Learning

flo hooks route --task "description"          # Route task to optimal agent
flo hooks learn --pattern "..." --domain "."  # Store a pattern
flo hooks patterns                            # List learned patterns
flo hooks consolidate                         # Promote/prune patterns

Gates

flo gate check-before-scan       # Blocks Glob/Grep if memory not searched
flo gate check-before-agent      # Blocks Agent tool if no TaskCreate
flo gate prompt-reminder         # Context bracket tracking
flo gate session-reset           # Reset gate state

Diagnostics

flo healer                       # Quick health check (environment, deps, config)
flo healer --fix                 # Auto-fix issues (memory DB, daemon, config, MCP, zombies)
flo diagnose                     # Full integration test (memory, swarm, hive, hooks, neural)
flo diagnose --suite memory      # Run only memory tests
flo diagnose --json              # JSON output for CI/automation

flo doctor is still accepted as an alias for flo healer — every flag and subcommand below works under either name.

flo healer — Health Check

flo healer runs 28 parallel health checks against your environment and reports pass/warn/fail for each:

Check	What it verifies
Version Freshness	Whether your installed MoFlo version matches the latest on npm (detects stale npx cache)
Node.js Version	Node.js >= 20 installed
npm Version	npm >= 9 installed
Claude Code CLI	claude command available
Git	Git installed
Git Repository	Project is inside a git repository
Config File	Valid moflo.yaml exists
Status Line	statusLine config wired in .claude/settings.json (auto-fixes when missing)
Daemon Status	Background daemon running (checks PID, cleans stale locks)
Memory Database	SQLite memory DB exists and is accessible
Embeddings	Vectors indexed in memory DB, HNSW index present
Embedding Hygiene	Indexer writes preserve existing embeddings instead of clobbering them
Test Directories	Test dirs from moflo.yaml exist on disk, reports auto-index status
MCP Servers	moflo MCP server configured in .mcp.json
Disk Space	Sufficient free disk space (warns at 80%, fails at 90%)
TypeScript	TypeScript compiler available
Semantic Quality	Semantic search returns relevant, varied results with acceptable similarity scores
Intelligence	SONA, ReasoningBank, PatternLearner, LoRA, EWC++, and RL subsystems are loaded
Spell Engine	Core spell modules, step commands, loaders, and index are present
Zombie Processes	No orphaned MoFlo node processes running
Subagent Health	Agent lifecycle (spawn → status → terminate) completes successfully
Spell Execution	End-to-end spell probe runs a real step and captures output
MCP Tool Invocation	MCP tool schemas are loaded and callable
MCP Spell Integration	Bridge between MCP tools and spell engine functions correctly
Hook Execution	Hook executor is functional and can fire hooks
Gate Health	All gate cases, hook bindings, and state file are intact
MofloDb Bridge	Memory DB adapter (sql.js + HNSW) is wired and routable
Sandbox Tier	Detects which sandbox backend is available (Docker / bwrap / sandbox-exec / none)

Auto-fix mode (flo healer --fix) attempts to repair each failing check automatically:

Issue	What --fix does
Missing memory database	Creates .swarm/ directory and initializes the SQLite DB
Embeddings not initialized	Initializes memory DB and runs embeddings init
Missing config file	Runs config init to generate defaults
Status line not wired	Adds statusLine config block to .claude/settings.json
Stale daemon lock	Removes stale .moflo/daemon.lock and restarts daemon
MCP server not configured	Runs claude mcp add moflo to register the server
Claude Code CLI missing	Installs @anthropic-ai/claude-code globally
Zombie processes	Kills orphaned MoFlo processes (tracked + OS-level scan)

After auto-fixing, healer re-runs all checks and shows the updated results. Issues that can't be fixed automatically are listed with manual fix commands.

Additional flags:

flo healer --install             # Auto-install missing Claude Code CLI
flo healer --kill-zombies        # Find and kill orphaned MoFlo processes
flo healer -c memory             # Check only a specific component
flo healer -c embeddings         # Check only embeddings health
flo healer --verbose             # Verbose output

/eldar — Consult the Eldar (project setup audit + wizard)

Where the Healer checks your moflo install, /eldar audits how Claude is set up to use the project — guidance, CLAUDE.md, memory namespaces, hook/MCP wiring, model routing, and stack-aware guidance gaps — then walks you through fixing whichever findings you pick. Use it when starting in a new project, when Claude feels lost or inefficient, or as a periodic health check.

/eldar                           # Read-only audit; categorized report + top-3 ranked recommendation
/eldar --fix                     # Audit, then interactive triage menu — pick which findings to address

The Eldar consult the Healer (they call flo healer --json as one of the audit checks) — they don't replace it. Categories audited include setup health, index freshness, version skew, model/token routing, CLAUDE.md size + reference integrity, guidance content + structure, memory health, hook/MCP wiring, settings sanity, spell + subagent inventory, stack → guidance cross-reference (detects tech from package.json/pyproject.toml/Cargo.toml/go.mod and flags every detected technology with no matching guidance doc — the highest-leverage finding for new adopters), and best-effort anti-pattern detection from history.

In --fix mode, each chosen finding drives the appropriate sub-flow: Healer for setup repair, the /guidance skill for guidance authoring (wizard, never autogen), a stack-aware scaffold for missing CLAUDE.md, flo init --upgrade for hook/MCP wiring. Every write is confirmed before it lands.

flo diagnose — Integration Tests

While healer checks your environment, diagnose exercises every subsystem end-to-end: memory CRUD, embedding generation, semantic search, swarm lifecycle, hive-mind consensus, task management, hooks, config, neural patterns, and init idempotency. All test data is cleaned up after each test — nothing is left behind.

GitHub Repository Setup

flo github setup                  # One-shot: generate CI + apply repo settings + branch protection
flo github setup --dry-run        # Preview everything without making changes
flo github ci                     # Generate .github/workflows/ci.yml from project config
flo github ci --dry-run           # Print CI config to stdout
flo github settings               # Apply repo settings + branch protection via gh CLI
flo github settings --dry-run     # Preview settings changes

flo github ci auto-detects your package manager (npm/pnpm/yarn/bun), TypeScript, and test directories from moflo.yaml and package.json, then generates a GitHub Actions CI pipeline with install, build, lint, type-check, and test steps.

flo github settings applies recommended defaults via gh CLI: delete-branch-on-merge, squash merge with PR title/body, auto-merge, linear history, and configurable branch protection (required reviews, dismiss stale reviews, block force pushes). Requires gh auth login.

System

flo init                          # Initialize project (one-time setup)
flo --version                    # Show version

What Ships Out of the Box

flo init wires up the following systems automatically. Here's what each one does, why it matters, and whether it's enabled by default.

Hooks (enabled OOTB)

Hooks are shell commands that Claude Code runs automatically at specific points in its lifecycle. MoFlo installs 23 hook bindings across 8 lifecycle events. You don't invoke these — they fire automatically.

Hook Event	What fires	What it does	Enabled OOTB
PreToolUse: Write/Edit	flo hooks pre-edit	Records which file is about to be edited, captures before-state for learning	Yes
PreToolUse: Glob/Grep	flo gate check-before-scan	Memory-first gate — blocks file exploration until memory is searched	Yes
PreToolUse: Read	flo gate check-before-read	Blocks reading guidance files directly until memory is searched	Yes
PreToolUse: Bash	flo gate check-dangerous-command	Safety check on shell commands	Yes
PreToolUse: Bash	flo gate check-before-pr	Validates PR readiness before gh pr create	Yes
PostToolUse: Write/Edit	flo hooks post-edit	Records edit outcome, optionally trains neural patterns	Yes
PostToolUse: Write/Edit	flo gate reset-edit-gates	Resets edit-related gate state after the write completes	Yes
PostToolUse: Agent	flo hooks post-task	Records task completion, feeds outcome into routing learner	Yes
PostToolUse: TaskCreate	flo gate record-task-created	Records that a task was registered (clears TaskCreate gate)	Yes
PostToolUse: Bash	flo gate check-bash-memory	Detects memory search commands in Bash (clears memory gate)	Yes
PostToolUse: Bash	flo gate record-test-run	Records test runs from Bash for the test-output gate	Yes
PostToolUse: Skill	flo gate record-skill-run	Records that a skill was invoked (clears skill-related gates)	Yes
PostToolUse: memory_search	flo gate record-memory-searched	Records that memory was searched (clears memory-first gate)	Yes
PostToolUse: TaskUpdate	flo gate check-task-transition	Validates task state transitions (prevents skipping states)	Yes
PostToolUse: memory_store	flo gate record-learnings-stored	Records that learnings were persisted to memory	Yes
UserPromptSubmit	prompt-hook.mjs	Resets per-prompt gate state, tracks context bracket, routes task to agent	Yes
SubagentStart	subagent-start	Injects context and guidance into spawned sub-agents	Yes
SessionStart	session-start-launcher.mjs	Launches auto-indexers (guidance, code map, tests), restores session state	Yes
SessionStart	auto-memory-hook.mjs	Imports auto-memory entries from Claude's persistent memory	Yes
Stop	flo hooks session-end	Persists session metrics, exports learning data	Yes
Stop	auto-memory-hook.mjs	Syncs auto-memory state on session close	Yes
PreCompact	flo gate compact-guidance	Injects guidance summary before context compaction	Yes
Notification	flo hooks notification	Routes Claude Code notifications through MoFlo	Yes

Systems (enabled OOTB)

These are the backend systems that hooks and commands interact with.

System	What It Does	Why It Matters	Enabled OOTB
Semantic Memory	SQLite database (sql.js/WASM) storing knowledge entries with 384-dim vector embeddings	Your AI assistant accumulates project knowledge across sessions instead of starting from scratch each time	Yes
HNSW Vector Search	Hierarchical Navigable Small World index for fast nearest-neighbor search	Searches across thousands of stored entries return in milliseconds instead of scanning linearly	Yes
Guidance Indexing	Chunks markdown docs into overlapping segments, embeds each with MiniLM-L6-v2	Your project documentation becomes searchable by meaning ("how does auth work?") not just keywords	Yes
Code Map	Parses source files for exports, classes, functions, types	The AI can answer "where is X defined?" from the index instead of running Glob/Grep	Yes
Test Indexing	Maps test files to their source targets based on naming patterns	The AI can answer "what tests cover X?" and identify untested code	Yes
Gates	Hook-based enforcement of memory-first and task-registration patterns	Prevents the AI from wasting tokens on blind exploration and untracked agent spawns	Yes
Context Tracking	Interaction counter with bracket classification (FRESH/MODERATE/DEPLETED/CRITICAL)	Warns before context quality degrades, suggests when to checkpoint or start fresh	Yes
Semantic Routing	Matches task descriptions to agent types using vector similarity against 12 built-in patterns	Routes work to the right specialist (security-architect, tester, coder, etc.) automatically	Yes
Learned Routing	Records task outcomes (agent type + success/failure) and feeds them back into routing	Routing gets smarter over time — successful patterns are weighted higher in future recommendations	Yes
SONA Learning	Self-Optimizing Neural Architecture that learns from task trajectories	Adapts routing weights based on actual outcomes, not just keyword matching	Yes
MicroLoRA Adaptation	Rank-2 LoRA weight updates from successful patterns (~1µs per adapt)	Fine-grained model adaptation without full retraining	Yes
EWC++ Consolidation	Elastic Weight Consolidation that prevents catastrophic forgetting	New learning doesn't overwrite patterns from earlier sessions	Yes
Session Persistence	Stop hook exports session metrics; SessionStart hook restores prior state	Patterns learned on Monday are available on Friday	Yes
Status Line	Live dashboard showing git branch, session state, memory stats, MCP status	At-a-glance visibility into what MoFlo is doing	Yes
MCP Tool Server	100+ MCP tools for memory, hooks, coordination, spells, swarm, etc. (schemas deferred by default)	Enables AI clients to interact with MoFlo programmatically	Yes (deferred)

Systems (available but off by default)

System	What It Does	How to Enable
Model Routing	Auto-selects haiku/sonnet/opus per task based on complexity analysis	model_routing.enabled: true in moflo.yaml
MCP Auto-Start	Starts MCP server automatically on session begin	mcp.auto_start: true in moflo.yaml
Tool Schema Eager Loading	Loads all MCP tool schemas (100+) at startup (instead of on-demand)	mcp.tool_defer: false in moflo.yaml

The Two-Layer Task System

MoFlo doesn't replace your AI client's task system — it wraps it. Your client (Claude Code, Cursor, or any MCP-capable tool) handles spawning agents and running code. MoFlo adds a coordination layer on top that handles memory, routing, and learning.

┌──────────────────────────────────────────────────┐
│  YOUR AI CLIENT (Execution Layer)                │
│  Spawns agents, runs code, streams output        │
│  TaskCreate → Agent → TaskUpdate → results       │
├──────────────────────────────────────────────────┤
│  MOFLO (Knowledge Layer)                         │
│  Routes tasks, gates agent spawns, stores        │
│  patterns, learns from outcomes                  │
└──────────────────────────────────────────────────┘

Here's how a typical task flows through both layers:

1. MoFlo routes — Before work starts, MoFlo analyzes the prompt and recommends an agent type and model tier via hook or MCP tool.
2. MoFlo gates — Before an agent can spawn, MoFlo verifies that memory was searched and a task was registered. This prevents blind exploration.
3. Your client executes — The actual agent runs through your client's native task system. MoFlo doesn't manage the agent — your client handles execution, output, and completion.
4. MoFlo learns — After the agent finishes, MoFlo records what worked (or didn't) in its memory database. Successful patterns feed into future routing.

The key insight: your client handles execution, MoFlo handles knowledge. Your client is good at spawning agents and running code. MoFlo is good at remembering what happened, routing to the right agent, and ensuring prior knowledge is checked before exploring from scratch.

For complex work, MoFlo structures tasks into waves — a research wave discovers context, then an implementation wave acts on it — with dependencies tracked through both the client's task system and MoFlo's coordination layer. The full integration pattern is documented in .claude/guidance/moflo-claude-swarm-cohesion.md.

The /flo skill ties both systems together for GitHub issues — driving the full process (research → enhance → implement → test → simplify → PR) with your client's agents for execution and MoFlo's memory for continuity.

Intelligent Agent Routing

MoFlo ships with 12 built-in task patterns that map common work to the right agent type:

Pattern	Keywords	Primary Agent
security-task	auth, password, encryption, CVE	security-architect
testing-task	test, spec, coverage, e2e	tester
database-task	schema, migration, SQL, ORM	architect
feature-task	implement, add, create, build	architect → coder
bugfix-task	bug, fix, error, crash, debug	coder
api-task	endpoint, REST, route, handler	architect → coder
...		(12 patterns total)

When you route a task (flo hooks route --task "..." or via MCP), MoFlo runs semantic similarity against these patterns using HNSW vector search and returns a ranked recommendation with confidence scores.

The routing gets smarter over time. Every time a task completes successfully, MoFlo's post-task hook records the outcome — the full task description, which agent handled it, and whether it succeeded. These learned patterns are combined with the built-in seeds on every future route call. Because learned patterns contain rich task descriptions (not just short keywords), they discriminate better as they accumulate.

Routing outcomes persist across sessions. You can inspect them with flo hooks patterns or transfer them between projects with flo hooks transfer.

Memory & Knowledge Storage

MoFlo uses a SQLite database (via sql.js/WASM — no native deps) to store three types of knowledge:

Namespace	What's Stored	How It Gets There
guidance	Chunked project docs (.claude/guidance/, docs/) with 384-dim embeddings	flo-index on session start
code-map	Structural index of source files (exports, classes, functions)	flo-codemap on session start
tests	Test file → source target reverse mapping	flo-testmap on session start
patterns	Learned patterns from successful task outcomes	Post-task hooks after agent work

Semantic search uses cosine similarity on neural embeddings (MiniLM-L6-v2, 384 dimensions). When Claude searches memory, it gets the most relevant chunks ranked by semantic similarity — not keyword matching.

Session start indexing — Background indexers (guidance, code map, tests) run on every session start. They're incremental — unchanged files are skipped — and run in parallel so they don't block the session.

Cross-session persistence — Everything stored in the database survives across sessions. Patterns learned on Monday are available on Friday. The stop hook exports session metrics, and the session-restore hook loads prior state.

For Claude

When flo init runs, it appends a section to your CLAUDE.md that teaches Claude:

• Always search memory before Glob/Grep/Read (enforced by gates)
• Use mcp__moflo__memory_search for knowledge retrieval
• Use /flo <issue> (or /fl) for issue execution
• Store learnings after task completion

Full Configuration Reference

flo init generates a moflo.yaml at your project root. Here's the complete set of options:

project:
  name: "my-project"

guidance:
  directories: [.claude/guidance]
  namespace: guidance

code_map:
  directories: [src, packages]
  extensions: [".ts", ".tsx"]
  exclude: [node_modules, dist]
  namespace: code-map

tests:
  directories: [tests, __tests__]
  patterns: ["*.test.*", "*.spec.*", "*.test-*"]
  extensions: [".ts", ".tsx", ".js", ".jsx"]
  exclude: [node_modules, coverage, dist]
  namespace: tests

gates:
  memory_first: true                 # Must search memory before file exploration
  task_create_first: true            # Must TaskCreate before Agent tool
  context_tracking: true             # Track context window depletion

auto_index:
  guidance: true                     # Auto-index docs on session start
  code_map: true                     # Auto-index code on session start
  tests: true                        # Auto-index test files on session start

mcp:
  tool_defer: true                   # Defer MCP tool schemas (100+); loaded on demand via ToolSearch
  auto_start: false                  # Auto-start MCP server on session begin

hooks:
  pre_edit: true                     # Track file edits for learning
  post_edit: true                    # Record edit outcomes
  pre_task: true                     # Agent routing before task spawn
  post_task: true                    # Record task results for learning
  gate: true                         # Gate enforcement
  route: true                        # Intelligent task routing
  stop_hook: true                    # Session-end persistence
  session_restore: true              # Restore session state on start

models:
  default: opus
  research: sonnet
  review: opus
  test: sonnet

model_routing:
  enabled: false                     # Set to true for automatic model selection
  confidence_threshold: 0.85
  cost_optimization: true
  circuit_breaker: true

status_line:
  enabled: true
  branding: "MoFlo V4"
  mode: compact                      # single-line, compact, or dashboard
  show_dir: true                      # current directory name (compact/dashboard only)
  show_git: true
  show_session: true
  show_swarm: true
  show_mcp: true

Tool Deferral

By default, tool_defer is true. MoFlo exposes 100+ MCP tools — loading all their schemas at conversation start consumes significant context. With deferral enabled, only tool names are listed at startup (compact), and full schemas are fetched on demand via ToolSearch when actually needed. Hooks and CLI commands continue to work normally since they call the daemon directly, not through MCP tool schemas.

Set tool_defer: false if you want all tool schemas available immediately (useful for offline/air-gapped environments where ToolSearch may not work).

Model Routing

By default, MoFlo uses static model preferences — each agent role uses the model specified in models:. This is predictable and gives you full control.

Set model_routing.enabled: true to enable intelligent routing, which analyzes each task's complexity and auto-selects the cheapest capable model:

Complexity	Model	Example Tasks
Low	Haiku	Typos, renames, config changes, formatting
Medium	Sonnet	Implement features, write tests, fix bugs
High	Opus	Architecture, security audits, complex debugging

The router learns from outcomes — if a model fails a task, the circuit breaker penalizes it and escalates to a more capable model.

You can pin specific agents even when routing is enabled:

model_routing:
  enabled: true
  agent_overrides:
    security-architect: opus     # Never downgrade security work
    researcher: sonnet           # Pin research to sonnet

Architecture

• 9 bin entries shipped with npm: flo (main CLI), moflo, claude-flow (aliases), flo-setup, flo-codemap, flo-search, flo-embeddings, flo-index, flo-testmap
• Project config system: moflo.yaml for per-project settings
• One-stop init: flo init generates everything needed for OOTB operation

Relationship to Ruflo / Claude Flow

MoFlo started from Ruflo/Claude Flow but is now an independent project. The two share roots and a few namespace conventions, but the codebases, runtime, and design priorities have fully diverged. MoFlo is shipped as a single npm package — install moflo, run flo init, and that's it.

Why I Made This

Ruflo/Claude Flow is an incredible piece of work. The engineering that rUv and the contributors put into the original — swarm topologies, hive-mind consensus, HNSW vector search, neural routing, and so much more — made it one of the most comprehensive agent orchestration frameworks available. It was built to support a wide range of scenarios: distributed systems, multi-agent swarms, enterprise orchestration, research workflows, and beyond.

My use case was just one of those many scenarios: day-to-day local coding, enhancing my normal Claude Code experience on a single project. The original supported this — it was all in there — but because the project served so many different needs, I found myself configuring and tailoring things for my specific setup each time I pulled in updates. That isn't a shortcoming of the original; it's the natural trade-off of a tool designed to be that flexible and powerful.

So I started from that foundation and narrowed the focus to my particular corner of it. I baked in the defaults I kept setting manually, added automatic indexing and memory gating at session start, and tuned the out-of-box experience so that npm install and flo init gets you straight to coding. Over time MoFlo grew its own architecture (workspace collapse, in-tree fastembed runtime, sql.js + HNSW memory layer, spell engine, daemon-driven scheduling) and the two projects fully diverged.

If you're exploring the full breadth of agent orchestration, go look at Ruflo/Claude Flow — it's the real deal. If your needs are similar to mine — a focused, opinionated local dev setup that just works — MoFlo is for you.

License

MIT