An update on what’s new in MoFlo — the open-source npm package that upgrades Claude Code with full project knowledge, persistent memory, sandboxed automation, and a swarm of agents that actually stay wired together.

---

• GitHub: github.com/eric-cielo/moflo
• npm: npmjs.com/package/moflo — npm install --save-dev moflo

---

You did everything right. You installed Claude Code. You added MoFlo. You ran flo init, watched the hooks wire themselves up, saw the index build, saw the green checkmarks. And yet — half a session in — Claude is still asking obvious questions, re-reading files it already knows, picking the wrong abstraction, ignoring a convention you wrote down somewhere three weeks ago.

It’s a frustrating place to be, and it’s not a bug. A perfectly installed agent with no information to act on is just an expensive guessing machine. CLAUDE.md is missing or sparse. There’s no project guidance covering the framework you actually use. Memory namespaces are empty. A hook didn’t get wired during an upgrade. Each gap is small. Together, they are the difference between an AI that ships features and an AI that wastes tokens.

This release ships three skills designed to find and close those gaps: /eldar, /guidance, and flo healer. Together they form an audit-and-remediate loop that takes a “set up but underperforming” Claude and turns it into one that earns its tokens.

The Eldar — your project’s wise counsel

Type /eldar in any Claude Code session and the Eldar perform a read-only audit of your moflo + Claude Code setup. They walk a fixed checklist — no kitchen sink, no surprises — and produce a single severity-ranked report:

• Setup health — every check the Healer reports (more on the Healer below).
• Index freshness — does .moflo/moflo.db exist, are the guidance and code-map namespaces populated, when were they last refreshed.
• Version skew — how far behind the latest moflo on npm you are.
• Model & token routing — is your sonnet→opus escalation rate suspicious? If so, point at the tuning guide.
• CLAUDE.md — present, sized reasonably, every relative path it cites resolves.
• Guidance content — how many guidance docs you have, sliced into “none / sparse / healthy”.
• Guidance structure — every existing doc is graded against the universal writing rules (delegated to /guidance -a).
• Memory health — entries in guidance, patterns, learnings.
• Hooks & MCP wiring — session-start hook present, MCP servers configured, pre-task and post-task hooks in settings.json.
• Spell inventory and subagent fleet — are you using the automation primitives, or are they sitting unused?
• Stack → guidance gaps — your package.json has Drizzle and React Native; your guidance directory has neither. That’s a gap, and it’s a top-3 recommendation every time.

The output is a single sortable table sorted error → warn → info, followed by the top 3 recommendations in plain English with rationale. No noise. No “11 things you might consider.” Just the things actually slowing Claude down on this project, ranked.

Add --fix and the Eldar shift from counselors to guides. They present a numbered triage menu, you pick the findings you want to address, and the Eldar walk you through each one — confirming every change before it lands. They never auto-write opinionated content into your repo. Your guidance, your CLAUDE.md, your conventions — those are your project’s policy. The Eldar elicit it; they do not invent it.

Where the tokens go

Several Eldar checks aren’t just about “is it set up” — they specifically target token waste, latency, and the small frictions that quietly drain a session. This is where the audit pays for itself:

• Model & routing stats — if the sonnet→opus escalation rate is high, the router is paying premium tokens for routine work. The Eldar pull stats from hooks_model-stats and point at the tuning guide.
• Permissions block — without one in .claude/settings.json, every file edit, bash call, and MCP tool becomes a confirmation prompt. The cost is your attention, not just tokens — but it compounds across a session and breaks Claude out of flow.
• Stale or empty index — if .moflo/moflo.db hasn’t been refreshed (or guidance/code-map namespaces are empty), semantic search misses and Claude re-explores files it already knows. This is the single most common “why does Claude keep grep-ing the same directory” failure mode.
• Empty subagent fleet — no project-specific subagents under .claude/agents/ means every task runs in the main context window. Longer context, higher cost per turn, and parallel work that should fan out gets serialized.
• Unused spells — flo spell list returning zero means an entire automation primitive is sitting on the shelf. The Eldar surface it as info, not warn — but they surface it.
• Repeated manual loops — if recent activity shows 5+ separate git status / git diff / run-tests sequences in a session, the Eldar flag it: that pattern is what /simplify exists to batch into one cheap pass.
• Version skew — every minor moflo release ships token-optimization fixes (cache warmups, dedupe gates, hook efficiency, indexer write-paths that don’t blow away embeddings). Falling 3+ minors behind compounds quickly.
• Hook & MCP wiring — a half-wired session-start hook means the launcher’s index refresh and memory pre-warm don’t run, and you pay for that on every prompt for the rest of the session.

Each finding above is small in isolation. Together, they’re the difference between a session that costs a dollar and a session that costs ten — and between a Claude that finishes the task in two turns and one that takes seven.

The Guidance — single source of truth for what Claude should follow

Guidance docs are how you tell Claude “in this project, we use Drizzle this way”, “tests live here, snapshots over there”, “never touch the migration runner without a pre-merge backup”. When they exist and they’re well-written, Claude reads them via semantic search before every meaningful task. When they’re absent or hedged into mush, Claude does what it always does with no rules: it guesses based on whatever the rest of the internet does.

The /guidance skill has two modes:

• Single-doc mode — point it at a topic (/guidance drizzle-conventions) and it walks you through creating a new doc, or improving an existing one, against the universal rules: imperative voice (“must”/”never”, not “should”/”might”), **Purpose:** line, specific H2 headings, decision tables instead of nested bullets, a 500-line cap, and a ## See Also section so docs cross-link.
• Audit mode (/guidance -a) — runs two passes. A structural audit grades every existing doc against the rules, surfacing the worst offenders in a sortable table. Then a gap analysis reads package.json, pyproject.toml, Cargo.toml, the source layout, your hooks and MCP tool directories, and CI workflows — and lists the high-leverage topics that should have a guidance doc but don’t, with severity weighted by how pervasively the concern shows up in your code.

This is the layer that pays the dividend. A single, well-written, regularly-fed guidance doc covering your ORM conventions can save dozens of round-trip explanations per week — Claude reads it once via the semantic index, and the convention is in context for every relevant task. That’s the difference between paying for the same explanation 50 times and paying for it once.

The Healer — keeping the install honest

The Healer (flo healer, the thematic alias for flo doctor) is the lower layer. Where the Eldar audit your configuration and /guidance audits your content, the Healer audits your installation: Node version, npm cache, the daemon, the memory database, the embeddings runtime, git, MCP servers, the Claude Code CLI itself, disk space, TypeScript, semantic indexing, intelligence pipelines, and — critically — the swarm and hive-mind tripwires that catch silent regressions in MoFlo’s headline coordination layer.

You can run it directly:

flo healer            # full check
flo healer --fix      # show or apply auto-fixes
flo healer -c memory  # one component
flo healer --json     # machine-readable output (used by /eldar)

You usually don’t have to. The Eldar invoke the Healer in step 1a of every audit and fold its findings into the report. When you choose “Run Healer” from /eldar --fix‘s triage menu, the Eldar pass the output through verbatim and surface anything that needs your hands.

How they hand off — one loop, three specialists

The three skills are designed as a single loop with clear ownership boundaries. No skill duplicates another’s checks; each hands off where its remit ends:

• Eldar → Healer for setup health (step 1a of every audit).
• Eldar → /guidance -a for guidance structure and gap analysis (step 1g, mandatory whenever you have at least one guidance doc).
• Eldar → /guidance single-doc mode for authoring any gap doc the user picks from the triage menu.
• Eldar → flo init --upgrade for hooks/MCP wiring repair.
• /guidance reads the universal rules from one source of truth (moflo-guidance-rules.md) and never paraphrases — so when the rules evolve, every audit and every authoring session inherits the change automatically.

That hand-off discipline matters because the alternative — three skills with overlapping checks — is how single-source-of-truth contracts rot. Run any one of these tools and you reach the same conclusions; the difference is just how deep you go.

What you actually do

If you’ve already got moflo installed, the new flow is two steps:

/eldar          # audit only — no writes
/eldar --fix    # audit, then triage menu, then walk through fixes

If you’re starting in a new repo where moflo just landed, run /eldar first. The audit will tell you in 30 seconds whether your install is wired, whether you have a CLAUDE.md, what guidance you’re missing for the stack actually in your package.json, and which two or three things to fix first. Then run /eldar --fix and let the Eldar walk you through each one.

For ongoing health, run /eldar as a periodic check — when Claude starts feeling sluggish, when guidance has drifted, after any significant refactor, or just every few weeks. It’s read-only and cheap.

Why this matters

Most “Claude isn’t working well” reports trace back not to the model and not to the tools, but to the gap between them — information. Empty guidance. A CLAUDE.md that drifted three releases ago. A hook that didn’t survive an upgrade. A memory namespace that nobody seeded. None of those gaps are dramatic; none of them break the build. They just quietly tax every session.

The Eldar exist to find those gaps and rank them — and, just as importantly, to surface the silent token taxes (sluggish routing, missing permissions, stale indexes, unused subagents, repeated manual loops) that quietly inflate every session bill. /guidance exists to close the content gaps in the form Claude can actually consume. The Healer exists to keep the foundation honest underneath. Three specialists, one loop, one outcome: an installation that earns its tokens instead of burning them.

MoFlo is, and will stay, free and open source. If your Claude Code sessions still feel like they’re starting cold every morning even after you set everything up, this is the next thing to try.

Ready to give Claude what it needs to excel? Summon the Eldar.

npm: npmjs.com/package/moflo — npm install --save-dev moflo

GitHub: github.com/eric-cielo/moflo