Creppy

A cartoon-crepe debugger assistant for the browser. Drive it with your favorite LLM coding agent to step through what your code actually does at runtime.

Creppy is a tiny, framework-agnostic library that puts a friendly crepe in the corner of your app. When you ask an AI agent (Claude, GPT, etc.) to "help me debug what happens when I click Submit", the agent instruments the relevant code path with await creppy.step(...) calls. At runtime, the application freezes at each step and a speech balloon explains — in plain English — what is about to happen, what state exists, what request is in flight, what came back.

It is essentially Chrome DevTools' step-debugger, but narrated by an LLM, in the user's own words, with the relevant DOM element highlighted on screen.

• 🥞 Crepe character in any screen corner — top-left, top-right, bottom-left, bottom-right.
• ⏸ Promise-barrier freeze — each await creppy.step(...) resolves only when the user clicks Next →.
• 🎯 Element highlighting — point a step at a CSS selector and Creppy outlines the element while that step is active.
• 🧠 LLM-friendly API designed to be written by agents. See AGENTS.md.
• 🪶 Zero runtime dependencies, ~20 KB, ESM + CJS + TypeScript types.
• 🔌 Framework-agnostic. Vanilla, React, Vue, Angular, Svelte — works in any browser app. Internal architecture is Model–View–Presenter so adapters can swap the View without touching the rest.

Install

npm install creppy

No CSS import needed — styles are auto-injected the first time Creppy mounts.

Quick start

import { creppy } from "creppy";

async function onSubmit(e) {
  e.preventDefault();
  creppy.start("Submit handler walkthrough");

  await creppy.step({
    type: "thinking",
    text: "User clicked Submit. Reading form values next.",
    target: "#submit",
  });

  const email = emailInput.value;
  await creppy.step({
    type: "info",
    text: "Got the email. About to POST /api/login.",
    detail: `email = ${JSON.stringify(email)}`,
  });

  const res = await fetch("/api/login", { method: "POST", body: ... });

  await creppy.step({
    type: res.ok ? "success" : "error",
    text: `Server returned ${res.status}.`,
  });

  creppy.complete("Done.");
}

Open the app, click Submit, click Next → to advance through each step. The app is genuinely paused between steps — there is no parallel timeline, no fake animation.

A full vanilla demo lives in examples/vanilla.html.

How it's meant to be used

The whole point of Creppy is that you don't write those await creppy.step(...) calls yourself. You ask your AI coding agent to do it:

"Using Creppy, walk me through what happens when I click Submit on the login form."

The agent reads your code, identifies the relevant flow, inserts the right step() calls at the meaningful moments, and hands the file back. You hit Submit and Creppy walks you through it.

Agents that need to know how to do this — point them at AGENTS.md. That file is written for any LLM, not just Claude, and includes the API, the mental model, the worked example, and common patterns.

API

import { creppy, createCreppy, createCreppyWithView, CreppyDismissedError } from "creppy";

creppy.mount(): void
creppy.start(title?: string): void
creppy.step({ text, type?, target?, detail? }): Promise<void>   // rejects with CreppyDismissedError on dismiss/destroy/restart
creppy.complete(text: string, type?: StepType): void
creppy.dismiss(): void
creppy.setPosition("top-left" | "top-right" | "bottom-left" | "bottom-right"): void
creppy.destroy(): void   // permanent for the singleton — subsequent calls throw

If a step is gating a side effect (charging a card, deleting a row), wrap your flow in try { … } catch (err) { if (err instanceof CreppyDismissedError) return; throw err; } so dismissing the bubble cleanly aborts. See AGENTS.md for the full pattern.

| field | type | meaning | |----------|-----------------------------------|---------------------------------------------------| | text | string | One-sentence narration shown in the balloon. | | type | "thinking" \| "info" \| "success" \| "error" | Visual category. Default "info". | | target | string \| Element | Optional element to outline while the step is active. | | detail | string | Optional monospace block under the text (payload, value, stack). |

creppy is a lazily-initialized singleton, also attached to window.creppy so agents can reach it from anywhere. Call createCreppy(opts) if you want your own instance with explicit options.

Options

createCreppy({
  position: "bottom-right",   // default corner
  title: "Creppy",            // default bubble title
  autoMount: true,            // mount to <body> immediately
  zIndex: 2147483000,
});

Framework adapters

Creppy's default View renders plain DOM, but the public CreppyView interface lets you replace it with a React/Vue/Angular tree while keeping the Model and Presenter unchanged:

import { createCreppyWithView, type CreppyView } from "creppy";

class MyReactView implements CreppyView { /* ... */ }

const creppy = createCreppyWithView(new MyReactView());

No first-party adapters are shipped in v0.1 — the default DOM view works inside any framework, since it renders to document.body outside the framework's tree.

Development

npm install
npm run build      # tsup → dist/index.{mjs,cjs,d.ts}
npm run typecheck

To run the demo locally:

npx serve -l 4178 .
# then open http://localhost:4178/examples/vanilla.html

(Plain python -m http.server will not work — it serves .mjs as text/html and the browser refuses to load it as a module.)

Architecture

Three layers, one-way data flow:

• Model (src/model.ts) — pure state container, no DOM, no promises.
• View (src/view.ts) — DOM rendering and user-event capture, no business logic.
• Presenter (src/presenter.ts) — owns the public API and the Promise-barrier freeze.

This separation is what makes a React/Vue/Angular adapter a swap of the View layer rather than a fork.

License

MIT