Moflo

MoFlo

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

Website · npm · GitHub

TL;DR

MoFlo makes Claude Code remember what it learns, check what it knows before exploring files, and get smarter over time — all automatically. Install it, run flo init, restart Claude Code, and everything just works: your docs and code are indexed on session start so Claude can search them instantly, gates prevent Claude 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. 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, run the /healer skill inside Claude Code (or flo healer from the CLI) after restarting — it runs full diagnostics. If anything fails, run /healer --fix to automatically fix issues.

Next Step: Consult the Eldar

After installing moflo, the single highest-leverage thing you can do for the best experience is run /eldar inside a Claude Code session.

Where /healer (or flo healer from the CLI) verifies that moflo itself is wired up correctly, /eldar audits how Claude is set up to actually use your project — guidance docs, CLAUDE.md, memory namespaces, hook/MCP wiring, model routing, and whether every technology in your stack (TypeScript, Python, Rust, Go, etc.) has matching guidance for Claude to lean on. The stack → guidance cross-reference alone is often the difference between "Claude feels lost in this codebase" and "Claude knows this codebase".

/eldar          # Read-only audit; categorized findings, severity-ranked
/eldar --fix    # Interactive triage — pick what to fix and the Eldar walk you through it

Run it on day one in any new project, any time Claude feels off, or as a periodic health check. Outside of the core install, this is the most impactful thing moflo offers — full details in the /eldar section [further down](#eldar--consult-the-eldar-project-setup-audit--wizard).

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.
• node:sqlite (built-in) — The memory database uses Node 22's built-in SQLite engine. No better-sqlite3 native bindings to compile, no WASM round-trip, 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.
• Claude Code is the only target — MoFlo is built and shipped for Anthropic's Claude Code (CLI, IDE extensions, web). It is not a Claude Desktop integration: nothing reads from or writes to ~/.claude/claude_desktop_config.json or %APPDATA%/Claude/, and adding paths there is always a bug. The MCP tools, memory system, and hooks could in principle work with any MCP-capable client, but Claude Code is the only surface we author for, test against, or accept bug reports on.
• 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. | | Reflection | Distills durable lessons from your sessions into searchable memory — automatically (auto-meditate), or on demand with /meditate. | | Cross-Install Sharing | Durable learnings follow you across git worktrees automatically (no setup) — and across your own machines or a whole team via flo memory sync or a git-tracked artifact. Structural namespaces stay local. [Full documentation →](.claude/guidance/shipped/moflo-cross-install-memory-sharing.md) | | 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 →](docs/SPELLS.md) | | /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 /healer skill (or flo healer from the CLI) 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

First-run heads-up: brief CPU spike during initial indexing

The very first time MoFlo runs in your project — typically right after flo init and the next session start — it builds the initial guidance, code map, and test indexes from scratch and generates 384-dim embeddings for every chunk. On a medium-sized project this takes one to a few minutes and you may see elevated CPU during that window. It runs in the background, so you can start working immediately; you just might hear your fans for a bit.

After that first pass, indexing is incremental and lazy — every subsequent session start only re-processes files that actually changed since the last run, which typically finishes in under a second with no perceptible CPU activity. The big one-time cost is a deliberate trade: pay it once, then every future session opens with your project already searchable by meaning.

> Tip: Let that initial indexing finish before running /healer (or flo healer). Healer's embeddings and semantic-quality checks expect the indexes to exist — if you run it mid-build it may flag warnings that resolve themselves the moment indexing completes.

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 Claude Code 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, Claude Code 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, Claude can search semantically ("how does auth work?") and get relevant documentation chunks ranked by

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: eric-cielo
• Source: eric-cielo/moflo
• License: MIT
• Homepage: https://cielolimitada.com/moflo

Install and usage instructions live in the source repository linked above.