The format is called a malleable HTML file. Its real extension is .html, and its open specification is at malleablehtmlfile.com.
HTML Clay is one app that hosts this format. The .htmlclay extension tells your operating system to use HTML Clay, just as .psd identifies Photoshop rather than the underlying image format.
HTML Clay keeps the file you opened, every file you save, and every change another program makes. Each one is a complete version.
Backups / notes.htmlclay
complete HTML files
Newest 20 kept, plus every version from the last 60 days
The history is deliberately ordinary. Every version is a complete, uncompressed .html file in the Backups folder.
Each version has a readable local timestamp in its name. Choose Backups from the tray to open the folder in your file manager. You can open and read any version even if HTML Clay is gone. Each one is a full, uncompressed copy, so saving a 1 MB file 20 times uses about 20 MB of disk space.
Before an old version replaces the current file, HTML Clay backs up what is there now. If that copy cannot be made, the restore is refused.
Rename or move a .htmlclay file and its history follows. Make a copy and the copy gets a fresh identity, so its edits never mix with the original. Plain .html files are the exception: their history is tied to their location, so moving them leaves that history behind.
Double click a file and it opens in your normal browser, in a normal tab. Trust a folder when the files inside belong together.
Every .htmlclay file inside opens editable without another prompt, including files added later. Relative links work like they do on any static site.
An editable page can upload a file to a folder beside it, such as assets-notes/. The page receives a relative URL. An upload can be up to 25 MB, and HTML Clay stores it once by content hash rather than repeating it as base64 inside every save and version.
A text editor, Git command, sync client, or local agent can rewrite the file. HTML Clay waits until the bytes stop changing. It then versions the file and updates the open page in place, without a reload.
When a document enables clayjs live sync, tabs in edit mode exchange unsaved DOM snapshots through HTML Clay. Identifiable dirty regions, the caret, and scroll position survive an incoming file change.
This works between tabs and windows on one machine. It is not multiplayer sync between computers.
A page can change only itself. A trusted folder is the one exception. Any HTML Clay file inside it can change any other file in that folder, including files added later. Untrust the folder and that permission ends.
Nothing outside your home folder can be opened at all. HTML Clay also refuses dotfiles, its settings, and its backups. A refusal looks the same whether the file exists or not, so a page cannot probe your disk by asking.
Your files stay on your machine. HTML Clay checks for a new version once at startup. It sends no file contents, and nothing else leaves your machine.
The full model, including the risks it accepts on purpose, is written down in SECURITY.md.
Small guarantees you would only find by looking for them. Most of the work is in keeping ordinary file operations ordinary.
Opening is read only. A file you open and never save stays byte for byte unchanged.
No script is ever injected into your page. HTML Clay adds a save token, a durable id, and one cookie before sending the page to your browser. It strips those additions before anything reaches disk.
A save replaces the whole file. HTML Clay writes and flushes a temporary file, then renames it over the target. On macOS and Linux, it also flushes the directory before reporting success.
Invalid bodies never reach disk. HTML Clay refuses empty bodies, non HTML bodies, JSON bodies, and anything over 50 MB.
Consecutive identical versions collapse. HTML Clay never stores the same content twice in a row.
Your own save does not echo back. The watcher suppresses the exact hash HTML Clay just wrote.
Half written files stay off screen. HTML Clay shows an outside change only after repeated reads return the same bytes.
A copied file forks its history. The original and the copy cannot quietly write into the same backup record.
An outside edit is backed up before your save wins. The save succeeds, and the previous bytes remain in Backups.
Opening a file leaves no permanent copy. If you open a file once and never save it, HTML Clay removes its history after a week.
All three open files in the default browser and provide a tray menu. Installation and permission handling differ today.
register.bat manuallyThe beta labels are honest ones: the Windows and Linux permission prompts have not yet been exercised on real machines, and both fail closed. On Linux, a missing dialog tool causes the request to be denied. Windows does not yet detect when a folder is replaced at the same path.
The file is also the interface.
The same local address that makes editing feel ordinary gives your scripts two narrow ways in. One asks a program to edit the file. The other reads the file as structured JSON. The source is public under a source available license, and this version converts to plain MIT in February 2028.
The wire is a per file channel between an open page and one command you started yourself.
htmlclay wire serve <file> -- <cmd>The command receives a small JSON request on stdin. Each line it prints becomes a progress update that the page can show. Exit 0 means the work is done. The program edits the file on disk with whatever tools it already has. That makes claude -p "$(cat)" a working AI handler with no extra code.
No HTML crosses the wire in either direction. The file is the only shared state. Requests are capped at 1 MiB, so nothing document sized can drift through the channel.
No tab needs to be open. An attached handler keeps watching the file. An agent that edits it at 3am still gets its writes versioned. HTML Clay enables history before the handler's first write. If the file cannot be read, it refuses to attach the handler instead of letting it run without versioning.
A page cannot pretend to be your handler. Request headers that a browser cannot suppress tell HTML Clay whether a request came from a browser or a local process. Anything that identifies itself as a browser is refused the handler role.
"Nobody was listening" is a distinct answer, not a timeout. The send response reports whether a handler queued the request, so a page never mistakes its own echo for delivery.
The full protocol is in docs/wire.md.
A file can publish a small read only API. Your script gets the fields the document chose to expose, without a browser or an HTML parser.
<h1>Hello</h1>
<ul><li class="i">one</li><li class="i">two</li></ul>
<script data-rules-name="api" data-rules-version="1">
{title: "h1", items: ".i[]"}
</script>$ curl http://127.0.0.1:52341/_/api/notes.htmlclay
{"title":"Hello","items":["one","two"]}The same file boundary applies. A data request can read only what a normal request could serve.
Read only by design. It creates no editing session, save token, or version.
The API uses the same rules dialect as the Hyperclay platform, so a rule written for either one works with the other. A caller can also pass ad hoc rules in the URL with ?data={...}. The API deliberately sends no CORS headers. As a result, a page served by another local server on your machine cannot read your files.
A local file, with the parts a document deserves.
Free to download and use. No account. Works offline.
Download HTML Clay