npm i oh-my-fable

The demos are magical. Then you point an agent at a real multi-hour task and it
loops on the same step, loses the plan somewhere in a 40-message chat history, and
— when your process restarts — forgets everything and starts over.

oh-my-fable encodes the way a strong reasoning model works a long task — the
mindset, not the model — into a harness: plan first, self-correct every step,
keep the thread, and finish. It's built around two mechanisms and one rule:

The whole run lives in a single RunContext — the only source of truth, and
always serializable. It's checkpointed after every step.

From that one rule you get the thing nobody else gives you: a crash is a pause.

_{The name is about the thinking, not a model lock-in — the mindset is Fable 5's, the
engine is whatever Provider you hand it (Anthropic, OpenAI-compatible, local, …).}

── run run_mqf… ──
  📋 planned 3 steps: outline → draft → edit
  ▶  outline
     → outlined
     💾 checkpoint saved
  ▶  draft
  💥 the process just died (power outage, OOM, deploy, whatever)

── resuming from the last checkpoint ──
  ▶  draft                ← picks up exactly where it died
     💾 checkpoint saved
  ▶  edit
  ✅ done

  steps: outline [done], draft [done], edit [done]

const result = await run(goal, { provider, store });   // crashes at step 2
// ...process restarts...
await resume(result.runId, { provider, store });        // finishes from step 2

That's examples/scripted-run.mjs — run it with npm run example, no API key needed.

The three things it does that most frameworks don't

1. It survives crashes (resumable by construction)

State doesn't live in memory or in a chat transcript — it lives in RunContext,
saved to disk after every step. Kill the process at step 47 of 60 and resume()
continues from step 47, plan and progress intact. Swap the FileStore for
SQLite/Redis by implementing one interface.

2. It plans first, then self-corrects (plan ≠ history)

The plan is structured data that lives outside the conversation, so the model
never loses track of "where am I" in a wall of text. After every step a reflector
checks the result against the goal and routes:

And it works in both directions: stopping early when the goal is met, and
refusing to stop when it isn't — when the plan runs out of steps but the
goal has successCriteria, a final exit check verifies them against the
recorded evidence and sends the run back to work if something is missing.
Plan exhaustion and goal completion are different events.

Replanning accumulates: finished steps are preserved verbatim; only the
remaining work is regenerated. Long tasks move forward instead of restarting.

3. It's deterministically testable (genuinely rare for an agent framework)

Because every model call is stateless, you can script the model and assert the
loop's behavior — no network, no flakiness:

import { run, ScriptedProvider, reply, MemoryStore } from "oh-my-fable";

const provider = new ScriptedProvider([
  reply.plan([{ id: "s1", intent: "do the thing" }]),
  reply.text("did it"),
  reply.reflection("goal_met"),
]);

const { status } = await run("do the thing", { provider, store: new MemoryStore() });
expect(status).toBe("done"); // fully deterministic

The whole harness is tested this way — crash-recovery, replan-accumulation,
budget halts, the tool loop — all without a single API call.

Quick start

import { run, AnthropicProvider } from "oh-my-fable";

const result = await run(
  {
    description: "Research the top 3 Rust web frameworks and write a comparison table",
    successCriteria: ["a markdown table comparing 3 frameworks exists"],
    constraints: ["only use information you can verify"],
  },
  { provider: new AnthropicProvider() }, // reads ANTHROPIC_API_KEY
);

console.log(result.status); // "done" | "halted" | "failed"
console.log(result.ctx.plan.steps);

npm i oh-my-fable        # zero runtime dependencies

Node ≥ 18. Ships with AnthropicProvider and OpenAICompatProvider (works with
OpenAI, Ollama, LM Studio, OpenRouter, Groq… — ollama("llama3.1") for a local
model with no key), both over fetch, no SDK. Or bring any model by implementing
the Provider interface (three methods).

AnthropicProvider defaults to claude-sonnet-5 and works with every current
flagship model (claude-opus-4-8, claude-fable-5) out of the box — it drops
the temperature parameter they reject, routes safety refusals to the
reflector instead of recording them as success, and on Fable-tier models opts
into the server-side refusal fallback (a classifier false-positive is
re-served by claude-opus-4-8 instead of failing the step). It
prompt-caches both the system+tools prefix and the replayed history by
default, so a long durable run re-reads its context at ~0.1× instead of full
price every step. Opt into { thinking: "adaptive", effort: "high" } for
harder planning. The claude provider can return real --output-format json
cost/usage and run Claude's own tools
({ tools: true, permissionMode: "acceptEdits" }).

Or use it from the terminal

Don't want to write code? It ships a CLI (zero extra deps):

npx oh-my-fable demo                       # watch crash → resume, no API key

# ⭐ already pay for Claude Code? drive it as a DURABLE, TOOL-USING agent — your
#    login, no separate API key, $0 per token. Claude edits files & runs commands:
npx oh-my-fable run "refactor utils.ts and run the tests" --provider claude --cli-tools

# pure-reasoning over the same login (no tools):
npx oh-my-fable run "outline a talk on durable agents" --provider claude

# or a LOCAL model (Ollama / LM Studio), also no key:
npx oh-my-fable run "outline a talk on durable agents" --provider ollama --model llama3.1

# or any hosted model:
export ANTHROPIC_API_KEY=sk-...
npx oh-my-fable run "summarize README.md into SUMMARY.md" --tools fs

npx oh-my-fable list                       # your saved runs
npx oh-my-fable show  run_abc123           # the run's plan, steps & budget as a timeline
npx oh-my-fable resume run_abc123          # continue one from its checkpoint

You don't need an Anthropic API key. Pick how it talks to a model:

Two ways to give an agent hands:

• --cli-tools (claude/codex) — the CLI runs its own tools (file edits, shell)
  on your subscription. oh-my-fable stays the durable planner/reflector around it:
  it plans, checkpoints every step, and reflects — Claude does the work. Tune with
  --permission-mode acceptEdits|dontAsk|plan and --allow "Read,Edit,Bash(npm test)".
• --tools fs (API providers) — the harness gives the agent a sandboxed
  read_file/write_file/list_dir, confined to the working directory.

You watch the plan form and each step get reflected on, live. Every run is
checkpointed, so resume <runId> always works — and show <runId> prints the
whole run (plan, steps, budget) from its serialized RunContext.

Tools

import { run, defineTool, AnthropicProvider } from "oh-my-fable";

const search = defineTool(
  "web_search",
  "Search the web and return results.",
  { type: "object", properties: { query: { type: "string" } }, required: ["query"] },
  async ({ query }) => ({ ok: true, output: await fetchResults(query) }),
);

await run(goal, { provider: new AnthropicProvider(), tools: [search] });

A tool that throws becomes an Observation, not a crash — the reflector decides
what to do about it.

Watch it work

await run(goal, {
  provider,
  onEvent: (e) => console.log(e.type, e),
  // plan_created · step_start · step_done · reflection · replan · compaction · checkpoint · exit_check · done · halted
});

It can't run away

Three hard ceilings, checked at the top of every loop turn, plus two recovery
caps — exceed any and it halts cleanly, preserving all work:

await run(goal, {
  provider,
  maxSteps: 50,            // total step budget
  maxTokens: 2_000_000,    // cumulative token budget — EVERY model call counts (planning, reflection, compaction, repair)
  maxWallClockMs: 1_800_000, // ACTIVE runtime only — downtime between crash and resume never counts
  maxStepAttempts: 3,      // a single step retried this many times → blocked
  maxReplans: 12,          // replan storm → halted
});

How it's built

A planner ↔ executor ↔ reflector loop over a serializable RunContext:

plan → [ budget? → next step → compact? → execute → reflect → checkpoint → route ] → exit check → done

• planner — goal → ordered steps, grounded in the tools the executor
  actually has; replan accumulates instead of resetting.
• executor — runs one step, including a provider-agnostic tool mini-loop.
• reflector — heuristics first (cheap, certain), then the model, with JSON
  self-repair and a conservative fallback (a wrong early exit is worse than one
  more loop). When the plan runs out of steps, it runs the final exit check
  against the success criteria — plan exhaustion is not goal completion.
• contextManager — folds old turns into digests so long runs stay inside the
  window; the plan is never compacted.
• store / budget — checkpoint after every step; guard against runaways.

Every piece is an interface you can replace without touching the core. The full
architecture writeup is in ARCHITECTURE.md.

Roadmap

• A web dashboard that tails a run's events and lets you resume from any checkpoint (show <runId> is the CLI version of this today).
• More providers in-repo (OpenAI-compatible, local) — though it's a 3-method interface.
• Parallel step execution for independent branches of the plan DAG.
• Human-in-the-loop: pause for approval as a first-class step status.

💖 Sponsor

Free, MIT, zero-dependency, built in spare time. If it saved your agent from
starting over:

• ⭐ Star the repo — it's how the next person building an agent finds it.
• 🍋 Sponsor via Lemon Squeezy — one-time or recurring.

License

MIT © oh-my-fable contributors