AIOS HTML Auto-Preview
A deliberately tiny VS Code extension that makes .html files open as a
rendered, interactive preview instead of raw source — whether you open them
from the Explorer or click them in the Claude Code chat panel. Built for
viewing AI-generated HTML artifacts in one click, without right-clicking and
without a heavyweight "office viewer" extension.
It's the HTML counterpart to
AIOS Markdown Auto-Preview:
both make AI-generated artifacts open the way you actually want to read them.
Install
Search "AIOS HTML Auto-Preview" in the Extensions view, or from a terminal:
# VS Code (Marketplace)
code --install-extension kyledunne.aios-html-auto-preview
# Cursor / VSCodium / Windsurf (Open VSX)
codium --install-extension kyledunne.aios-html-auto-preview
To opt a whole project in automatically, add it to the repo's
.vscode/extensions.json recommendations:
{ "recommendations": ["kyledunne.aios-html-auto-preview"] }
How it works
Two cooperating pieces, so .html renders no matter how it was opened:
A custom editor for *.html (aios.htmlPreview) that renders the file in
a sandboxed webview — injecting a <base href> so relative resources
(./style.css, images) resolve, and letting inline + CDN scripts run. It's
registered with priority: "option", so on its own it takes over only when a
workspace opts in by associating *.html with it (covers Explorer / Quick
Open opens).
A tab-watcher (window.tabGroups.onDidChangeTabs) for the case
associations can't reach: the Claude Code chat panel is a closed webview
that bypasses editorAssociations and force-opens source. When an .html
appears as a source tab the extension didn't expect, it closes it and reopens
it with the custom editor above. Net effect: click an .html chat link, it
opens rendered. (Brief source flash.)
It distinguishes intent structurally, not by timing, so "Reopen as source
file" still sticks: a file it just showed as preview, reopened as source, is a
deliberate downgrade and is left alone; a fresh forced-source open is swapped.
Pairing it with the association (recommended)
The watcher alone handles chat links. For Explorer / Quick Open opens to render
too, associate *.html with the custom editor in your settings:
{ "workbench.editorAssociations": { "*.html": "aios.htmlPreview" } }
Reading source when you want it
- On a preview, click the "Open Source" button (the go-to-file icon) in the
editor title bar — it swaps that tab to source in place and sticks.
- Command Palette → AIOS: Open This HTML as Source.
- Turn it off entirely: AIOS: Toggle HTML Auto-Preview, or set
htmlPreview.enabled to false.
What renders well
- Self-contained artifacts: inline
<script>/<style> + CDN tags (React,
Tailwind, etc.) — the common case.
- Relative resources, via the injected
<base> + webview local-resource roots.
- Live reload: edit in a split text editor and the preview refreshes.
What won't render
- Pages needing a real local server (
fetch('/api/...'), client-side
routing). For those use Microsoft's Live Preview (server-backed); the two
are complementary. Live Preview registers no custom editor, so it cannot be a
one-click default — which is exactly why this exists.
Troubleshooting
Set htmlPreview.debug to true to log every tab event and swap decision to the
"AIOS HTML Auto-Preview" output channel.
Part of the AIOS starter pack.
