html-explainer

What It Does

html-explainer helps Claude Code create HTML artifacts that are worth opening.

It is not HTML for decoration. It is HTML when a browser view helps someone inspect evidence, understand risk, compare options, make a decision, continue work, or save useful context for later.

Core path:

intent -> evidence -> visual understanding -> decision -> next action -> reusable memory

The user sees a clear artifact. The repo provides the quiet process behind it: routing, evidence checks, delivery audit, goal contracts, optional /goal autonomous closeout, local memory, and re-entry prompts.

Open a demo artifact:

examples/before-after-decision.example.html

Who It Is For

Use it when Claude Code work needs more than a chat answer:

• repo recaps and re-entry;
• plan, diff, and PR reviews;
• architecture and workflow maps;
• research comparisons;
• decision decks;
• prompt or agent behavior tuning;
• thinking through unclear ideas;
• saving useful artifacts into a local knowledge base.

Do not use it for short answers, single commands, tiny facts, or low-consequence notes.

Install

curl -fsSL https://raw.githubusercontent.com/ramsani/html-explainer/main/install.sh | bash

Restart Claude Code after installation.

To inspect first:

git clone https://github.com/ramsani/html-explainer.git /tmp/html-explainer
cd /tmp/html-explainer
DRY_RUN=1 INSTALL_UPSTREAM=0 FETCH_EXAMPLES=0 bash install.sh
bash install.sh

The installer adds slash commands, the thariq-html-effectiveness skill, docs, patterns, runtime scripts, examples, and a managed block in ~/.claude/CLAUDE.md. Existing content is backed up before replacement.

First Command To Try

Start here when you are not sure HTML is worth it:

/pick-the-right-html revisa esta tarea y dime qué artefacto HTML conviene crear. No generes todavía el HTML.

If you already know you want the artifact:

/make-the-right-html genera el artefacto HTML correcto con evidencia, riesgos, incertidumbre, siguiente acción y prompt listo para copiar.

What You Get After One Command

• a local HTML artifact you can open immediately;
• visible evidence, risk, recommendation, and next action;
• a quality result before delivery;
• a save, private, refresh, supersede, discard, or do-not-save decision;
• a copy-ready continuation prompt;
• a reusable knowledge-base entry when the artifact is worth keeping.

Core Commands

Command	Use it when you want to...
/pick-the-right-html	Decide whether HTML is worth it and which artifact fits.
/make-the-right-html	Generate a verified HTML artifact.
/check-the-plan	Review a plan before coding.
/check-the-diff	Review a diff or PR before accepting it.
/reenter-project	Understand a repo quickly and see the next action.
/build-decision-tool	Build a temporary editor, triage board, tuner, or config tool.
/audit-html	Check whether an existing artifact is actually useful.
/think-with-me-about	Turn a vague topic into a visual thinking surface with evidence, stress testing, action, and re-entry.
/open-html-explainer-memory	Open the local knowledge base of saved artifacts.

What Good Output Looks Like

A good artifact makes the next useful action obvious.

It should show:

• what the user is trying to decide;
• what evidence was inspected;
• what is fact, inference, assumption, or unknown;
• why HTML helps more than Markdown;
• the recommendation, risk, and next action early;
• a copy-ready next prompt;
• whether to save, keep private, refresh, supersede, discard, or not save it.

Interactive artifacts must produce usable output: copied prompt, Markdown, JSON, config, checklist, issue body, or another exportable result.

Generated HTML is expected to pass deliver-artifact.py at 90+ before delivery. Each HTML command points to a goal contract that defines the completion standard. To activate Claude Code's autonomous /goal loop, start the request with /goal.

Local Memory

Useful artifacts can be saved outside the repo under:

~/.claude/html-explainer/outputs/

The local knowledge base is:

open ~/.claude/html-explainer/outputs/index.html

It shows saved pages, topics, Maps of Content, resurfacing suggestions, related artifacts, metadata, local annotations, and copy-ready re-entry prompts.

From Claude Code, use:

/open-html-explainer-memory

Autonomous Closeout

For longer work, use Claude Code's /goal so Claude keeps going until a verifiable finish line is met:

/goal html-explainer V1 is complete when all validation scripts and smoke tests pass, README/CI/CONTRIBUTING list the same checks, and git status shows no generated junk.

Use it for audits, PR closure, artifact delivery, memory validation, and V1-style verification. Do not use it for small questions.

Goal contracts are always available as the finish line for each command. The autonomous /goal loop runs only when you invoke /goal explicitly.

The scripts remain the cheap CI floor; /goal decides whether the whole job is actually finished and whether the result is truly useful from the evidence Claude reports.

Each HTML-producing command points to a reusable goal contract. If HTML is generated, the command must run deliver-artifact.py before the final response; the goal contract treats skipped delivery as unfinished work.

Example:

/goal use /think-with-me-about to analyze this repo's real value. Do not stop until the generated HTML passes deliver-artifact.py at 90+, has 0 hard fails, includes a memory decision, next action, and a copy-ready continuation prompt.

More examples: docs/GOAL_WORKFLOWS.md.

The reusable goal contracts live in goals/. The completion model is documented in docs/COMPLETION_MODEL.md.

Verify Locally

Run the same checks expected from contributors and CI:

bash -n install.sh uninstall.sh scripts/*.sh
scripts/validate-patterns.sh
scripts/validate-commands.sh
scripts/validate-examples.sh
scripts/validate-goals.sh
scripts/validate-golden-artifacts.sh
scripts/validate-scenarios.sh
scripts/smoke-install.sh
scripts/smoke-uninstall.sh
scripts/smoke-artifact-memory.sh
DRY_RUN=1 INSTALL_UPSTREAM=0 FETCH_EXAMPLES=0 bash install.sh

For the docs reading order, see docs/DOCS_MAP.md.

Uninstall

Preview:

DRY_RUN=1 bash uninstall.sh

Restore latest backup, or remove managed files if no backup exists:

bash uninstall.sh

Remove without restoring backup:

RESTORE_BACKUP=0 bash uninstall.sh

Remove and delete backups:

KEEP_BACKUPS=0 bash uninstall.sh

Credits

This project is an independent integration layer inspired by and built around:

• visual-explainer by Nico Bailon;
• "The unreasonable effectiveness of HTML" by Thariq S. Bate;
• skills by Matt Pocock.

It is not an official project of Nico Bailon, Thariq S. Bate, Matt Pocock, Anthropic, or Claude Code.

See CREDITS.md, CHANGELOG.md, and CONTRIBUTING.md.