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.

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 from successful patterns
  • 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 →
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.)
Spec-Driven Development	/flo -sd runs a spec → plan → implement → verify cycle with memory-indexed artifacts. Opt-in, but once armed both halves are enforced: an implement gate blocks source edits until the plan is reviewed, and verify-before-done gates the PR. Human review is optional (sdd.human_checkpoints, off by default); spec+plan auto-embed into the PR body (embed_in_pr), or point sdd.specs_dir at a tracked path. Details →
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 similarity, or ask "where is the user model defined?" and get a direct answer from the code map — all without touching the filesystem.

Learning From Your Sessions

MoFlo turns the work you do into durable knowledge. A lesson worth keeping — a reusable pattern, a gotcha that cost you an hour, a decision and the rationale behind it — lands in the learnings memory namespace, where it's embedded and semantically searchable in every future session. Two paths feed that namespace: one you trigger, one that runs on its own.

/meditate — deliberate retrospective

Run /meditate at the end of a meaningful chunk of work. It reviews the session, distills the handful of lessons that would help a future session on a different task, deduplicates them against what's already stored, and writes the survivors to learnings. It's the curated pass — you choose when to capture, and it keeps only high-signal items (an empty reflection is a valid result, not a failure to pad).

/meditate                  # Review the whole session and store durable lessons
/meditate --preview        # Show the candidate lessons without writing anything
/meditate <focus>          # Scope the retrospective to one thread, e.g. "the auth refactor"

Auto-meditate — the automatic counterpart

Auto-meditate does the same job without being asked. While you work, a lightweight hook notices when a durable lesson emerges — a correction, an error you fixed, a decision you made. At the next session start, a brief background pass distills those into learnings using the same durability bar and dedup-then-store protocol as /meditate. It reuses your existing Claude Code session (no extra API key), runs in the background, and ships on by default.

auto_meditate:
  enabled: true            # Set to false to opt out — /meditate still works manually

The two are complementary: auto-meditate is the always-on safety net, /meditate is the deliberate, curated pass. Both write to the same learnings namespace and both deduplicate, so neither pollutes the other — and anything they store is available to semantic search from then on.

Sharing learnings across installations

The learnings (and knowledge) namespaces are the durable slice of memory — user-authored and worth carrying across checkouts. The rest of the DB (code-map, guidance chunks, run state) is structural or ephemeral and rebuilds cheaply, so it stays local. For ongoing sync MoFlo shares only the durable slice — never live-shares the whole moflo.db between two daemons, which would make each daemon's in-memory search index diverge.

Pick the mechanism by topology:

You want to share across…	Use	How
Git worktrees / Conductor workspaces (same machine)	Automatic — nothing to set	Learnings converge across worktrees at session-start (stored at <git-common-dir>/moflo/durable.db). Override with memory.durable_path; opt out with memory.worktree_sharing: false
Your own laptop + desktop + CI	flo memory sync --to/--from <file>	Export to a synced folder (Dropbox/iCloud) or a copied file, import on the other machine
A whole team on one repo	flo memory team-export → commit .moflo/shared/learnings.jsonl	Teammates' session-start import-merges it after git pull (first-write-wins; author provenance retained)
A fresh workspace that must be ready fast	flo memory backup/restore or memory.hydrate_from	Seed a new workspace from a whole-DB snapshot so it's searchable on session one — no cold reindex. Safe because each workspace owns its own copy (a one-time restore, not live sharing)

Verify your setup with flo doctor -c shared-db (it warns if you've accidentally pointed at a full moflo.db for live sharing). Full guide: moflo-cross-install-memory-sharing.md.

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.
Verify-before-done (on by default)	Claude must verify the change end-to-end (the /verify skill) before gh pr create	Before gh pr create (docs-only diffs exempt)	Enforces "prove it works before done." On by default since #1294 (/flo delegates to /verify and reuses its test run — no double verify). Opt out with verify_before_done: false or --no-verify. Pairs with the Spec-Driven Development cycle, which gives verification its acceptance criteria.
Implement gate (SDD front half)	When a run is armed for SDD, Claude must author a spec and get its plan reviewed before editing source	Before every source Write/Edit, when -sd/sdd.default armed the run	Makes the SDD front half enforced, not advisory (#1297): a spec-gated run can't skip to implementation. No-op for non-SDD work. Opt out per-project with sdd_gate: false, per-run with --no-sdd. Pairs with verify-before-done to gate both ends of the cycle.

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
  verify_before_done: true    # On by default (#1294); set false to skip /verify before `gh pr create`

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

The /flo Skill

Inside Claude Code, 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)
/flo -w <issue>               # Worktree: run the work in a fresh git worktree (aliases: -wt, --worktree)
/flo -sd <issue>              # SDD: spec → plan → implement → verify (implies --verify)
/flo -v <issue>               # Verify-before-done only (no spec/plan front-half)
/flo -m <issue>               # Auto-merge the PR once required checks pass

Flags compose: e.g. /flo -sd -m <issue> runs the SDD cycle and auto-merges. Each modifier has a --no-* form (--no-sdd, --no-verify, --no-merge) to override a moflo.yaml default for a single run — including --no-verify, since verify-before-done is on by default. For full options and details, type /flo with no arguments — Claude Code will display the complete skill documentation. Also available as /fl.

Spec-Driven Development (SDD)

/flo can run the full spec → plan → (review) → implement → verify cycle — the 2026 agentic-coding pattern — with two independent modifiers. Turning SDD on is opt-in, but once a run is armed for it (via -sd or sdd.default) both halves are enforced: the front half by an implement gate, the back half by verify-before-done.

• -sd / --sdd (opt-in; enforced once on) — author a spec (the what + acceptance criteria) and a plan (the steps) before implementing. When armed, the check-before-implement gate blocks every source Write/Edit until the spec exists and its plan is reviewed (#1297) — a run can't skip straight to code. Artifacts persist as Markdown at <specs_dir>/<slug>/{spec,plan}.md (default .moflo/specs) and are indexed into memory, so prior specs are searchable across sessions. Implies --verify.
• -v / --verify (on by default) — the verify half: a normal run plus the verify-before-done gate. It runs the /verify skill, which exercises the change end-to-end against its acceptance criteria and reports a per-criterion PASS/FAIL, reusing the run's own tests (no double verify). Runs by default; --no-verify skips it. Separable from SDD, so you get "prove it works" without the spec ceremony.

Human review is optional and off by default. moflo stays autonomous: the front half self-advances its spec/plan review checkpoints without stopping. Set sdd.human_checkpoints: true to sit in the loop and approve each artifact by hand before the cycle proceeds.

Both compose with execution mode (-n/-s/-h) and --worktree, and default from moflo.yaml:

sdd:
  default: false              # true → every /flo run uses the SDD cycle unless --no-sdd
  specs_dir: .moflo/specs     # where spec/plan artifacts are written (see below)
  human_checkpoints: false    # true → pause for human approval at spec & plan review (default: autonomous)
  embed_in_pr: true           # true → append spec+plan to the PR body so reasoning is reviewable
gates:
  verify_before_done: true    # on by default (#1294); false → skip /verify unless -v. Per-run: --no-verify
  sdd_gate: true              # on by default (#1297); false → don't enforce the spec→plan front half

On upgrade, consumers with no verify_before_done key start enforcing verify-before-done; an explicit value is preserved. sdd_gate only bites when a run is actually armed for SDD, so non-SDD work is unaffected. Docs-only diffs are exempt, so a pure-docs PR is never blocked.

Where specs live — and making them reviewable. By default spec/plan artifacts are written under .moflo/specs, which flo init gitignores — so they stay local and never bloat source control — and (with embed_in_pr, the default) the spec + plan are appended to the PR body, so the reasoning is reviewable in the PR even while the files stay local. If you'd rather source-control the artifacts, point sdd.specs_dir at a tracked path (e.g. docs/specs or .specs) and commit them normally; no gitignore surgery required — the two mechanisms compose. The path is written with / and resolved cross-platform. If you set it to a directory already covered by guidance.directories, moflo indexes the specs once (as guidance) rather than twice.

--sdd implies --verify (a spec/plan without an enforced verify step drifts). Manage artifacts directly with flo sdd (spec, plan, review, check, embed, list), and start from a fuzzy idea with /commune, which can hand its synthesized spec straight into the SDD spine. Wiring status is reported by /healer (and /eldar).

Auto-merge

• -m / --merge — after the PR is opened, await its merge preconditions and merge it, instead of stopping at "PR opened". Orthogonal to execution mode (-n/-s/-h), --worktree, and --sdd/--verify, and always runs after the quality gates (tests, simplify, learnings, verify) have let gh pr create through — so --merge never bypasses a gate.

It prefers GitHub-native auto-merge, falls back to poll-then-merge once required checks are green, and — when the only remaining blocker is review-required on a repo you administer (e.g. a solo repo where GitHub blocks self-approval) — auto-attempts an admin squash-merge. If an unattended admin merge is denied by Claude Code's permission classifier (headless/cron runs), it hands you a copy-paste command rather than looping. It re-confirms checks are green before any admin merge, and never --admin over a red or pending required check.

Default seeds from moflo.yaml; the per-run flag overrides, and --no-merge opts a single run out:

merge:
  auto: false                 # true → every /flo run auto-merges its PR unless --no-merge

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 Claude Code, 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 — moflo's localhost daemon dashboard — surfaces live schedules, recent executions, and per-schedule controls (disable / re-enable / run now), alongside worker health, memory stats, and Claude Code session stats. Ask /luminarium in your Claude session and it'll print the link.

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 Claude Code, 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. Default writes guidance for Claude into .claude/guidance/ as Markdown applying moflo's universal rules. -h switches the audience to humans (lighter ruleset, writes into docs/