Think-In-HTML

Point it at a file. Get back one self-contained HTML page that teaches that file — with a working interactive model of what the code actually does. No server, no build step, no dependencies. One file you can email to anyone.

▶️ See four real examples →

Don't take the description's word for it — the output is the pitch:

• 📈 The Pricing Desk — an AI price suggestion, clamped live on a number line. Ask the AI, toggle "let it go rogue," watch the guardrail catch it.
• ⏱️ The Window — a rate limiter as a live ops dashboard. Fire requests, watch 200s flip to 429, flip "infra down" to see it fail open.

Both were generated by the same tool from real production code, with zero shared design — that's the point. Every page is authored fresh for its subject: its own layout, its own visual system, its own interactive model. No two outputs look alike.

Note: Think-In-HTML is an instruction engine plus a self-contained-output validator — the authoring is done by an AI coding tool you already use (Claude Code, Cursor, or Codex). It is not a standalone generator.

Why

Reading code is hard. Reading someone else's code is harder. And if you're not a developer at all, it's nearly impossible.

Think-In-HTML turns this:

a folder of source files you've never seen before

Into this:

one bespoke interactive HTML page, designed for this subject, that walks you through it

Every explainer is built fresh for its subject, but the engine is guided to reliably include:

• Plain-language explanations — like a patient teacher, not like API docs
• A working interactive model of the core mechanic — not a decorative animation, but real logic from the source (the actual thresholds, states, or formulas) that you can drive yourself
• A bespoke visual design — palette, layout, and motif chosen to fit the subject, not picked from a preset list
• Real code, shown and explained — actual snippets from the source, in teacher voice
• A crisp "aha" — the one insight the lesson is built around
• A recap — what to walk away with

The output is one .html file. No server. No build step. Drag it into a browser, attach it to a PR, send it on Slack. It just works — and it's guaranteed self-contained (see Self-contained, guaranteed below).

Install

Free, and hosted only on GitHub — no npm package to install.

Clone + wire the adapter (recommended)

Requires Node.js ≥ 18:

git clone https://github.com/vibhusharma101/Think-In-HTML.git
node Think-In-HTML/bin/cli.mjs init

init auto-detects your AI tool (Claude Code, Cursor, Codex), copies the engine into
think-in-html/core/ in your project, and wires up the adapter. Nothing else to configure.

One-liner (no manual clone step)

curl -fsSL https://raw.githubusercontent.com/vibhusharma101/Think-In-HTML/main/install.sh | bash

Does the same thing as init above — clones the repo to a temp dir, copies the engine into
think-in-html/core/ in your current project, and wires up whichever AI tool it detects.

CLI commands (run from inside the clone)

node bin/cli.mjs init                                    # wire the adapter into this project
node bin/cli.mjs instructions code                       # print freeform generation guidance (code|thinking|text)
node bin/cli.mjs instructions code --blocks               # print the legacy schema/blocks guidance instead
node bin/cli.mjs check output.html                        # verify a generated file is self-contained
node bin/cli.mjs build analysis.json -o output.html       # build HTML from JSON (--blocks mode only)
node bin/cli.mjs --help

Want the shorter think-in-html <command> form? Add a shell alias:
alias think-in-html="node $(pwd)/Think-In-HTML/bin/cli.mjs".

Usage

Claude Code

/think-in-html src/auth/login.ts
/think-in-html src/api/ --mode code
/think-in-html thinking-log.txt --mode thinking
/think-in-html src/auth/login.ts --blocks    # legacy templated engine instead of freeform

Cursor

Ask in chat:

"Use think-in-html to explain src/auth/login.ts"

Codex

Ask:

"Run think-in-html on src/api/"

Output

Every command produces a single output.html — open it in your browser.

Who is this for?

How it works

Think-In-HTML has two generation modes. Freeform is the default.

Your code / transcript / text
   ↓
AI reads core/instructions/FREEFORM.md — picks the one mechanic worth making tangible,
   chooses a bespoke design, writes a complete self-contained output.html
   ↓
think-in-html check output.html — verifies it's self-contained (no external resources)

There's also a legacy blocks mode (--blocks): the AI emits structured JSON (never raw HTML) against a fixed schema, and a pre-built, tested renderer turns it into the page — consistent output built from a kit of teaching blocks and four preset visual skins. Useful if you want the older, more predictable template instead of a bespoke one.

Your code (--blocks)
   ↓
AI reads core/instructions/ANALYZE.md → emits analysis.json (validated against a schema)
   ↓
Pre-built HTML shell renders the JSON → one self-contained output.html

Self-contained, guaranteed

Freeform trades a fixed template for full design freedom, so the one thing the engine still enforces automatically is that the output never depends on the network. core/build/check-html.mjs (wired up as think-in-html check) rejects any external <script>/<link>/<img>, @import, or remote CSS url(), and requires the CSP <meta> tag every generated page ships with. Run it on any output before you rely on it.

Works with any AI coding tool

Think-In-HTML is not locked to one tool. The core engine is portable — thin adapters wire it into whatever you use:

Modes

Modes describe the input, independent of freeform vs. blocks generation. All three work with either generation mode.

Examples

Open the live gallery — or jump straight into a generated lesson:

Freeform (bespoke design + interactive model):

• The Pricing Desk — an AI price suggestion clamped to the live market, explored on a number line (code mode).
• The Window — a fixed-window rate limiter as a live ops dashboard (code mode).

Blocks (schema-validated teaching blocks + preset skins):

• How Think-In-HTML Works — the tool explaining itself, via a film-studio analogy (code mode).
• Inside EPRx Exchange — plastic-credit compliance taught through a carbon-offset analogy (code mode).

Each is a single self-contained .html file — click a link above to try it live, or open the committed copy in examples/ directly in any browser. No server needed.

Privacy

The generated HTML embeds source code into a shareable file. Only share artifacts for code you own or have permission to distribute.

Contributing

Start with CONTRIBUTING.md — setup, ground rules, and how to test a change.

The architecture has clean extension points, each covered in docs/extending.md:

• Add a tool adapter to support a new AI tool — a single thin file (see adapters/README.md).
• Add a mode (e.g. "database schema explorer") — a mode-*.md instruction file plus a schema enum entry.
• Add a block type (blocks mode) — a new teaching primitive in the schema, renderer, and instructions.
• Tune the freeform rubric — core/instructions/FREEFORM.md is the quality bar every bespoke page is judged against.

The schema reference documents the analysis.json contract that blocks-mode contributions target.

Maintainers

npm publishing is paused for now — the repo itself is the distribution channel (see
Install above). PUBLISHING.md is kept for when that resumes.

License

MIT