- HTML Clay
- Docs
- Programs
- Document programs
Document programs
How a document asks a local program to do work, how to attach one from the terminal, and what the approval covers.
A document program is a command on your computer that a page asks to do work by sending it a request. The program edits the file on disk with whatever tools it already has, and the change reaches the page like any other file change. In code and error text, HTML Clay calls a document program a helper.
Before you start#
You need HTML Clay installed and a file that opens through it. Get started covers that setup. The shell example below is for macOS and Linux. Install ripgrep and jq first. Check them in your login shell, whose PATH HTML Clay uses for document programs:
$SHELL -lc 'rg --version && jq --version'
The command prints a version line for each tool.
On Linux, document permission prompts also need zenity or kdialog. On Windows, a document program must be a .exe, .bat or .cmd file.
Only connect a program you trust with your account. It runs as you and can read or change any file you can access.
Attach from the terminal#
This example searches the saved HTML of a small todo list. Searching does not change the file.
Save this page as todo.htmlclay in a folder inside your home folder, such as ~/Documents/todo:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Todo</title>
</head>
<body>
<h1>Todo</h1>
<ul>
<li class="todo" data-done="false">Buy milk</li>
<li class="todo" data-done="false">Book dentist</li>
</ul>
<script src="https://clayjs.com/v1/clay.js?plugins=wire"></script>
<script>
clay.ready.then(() => {
const panel = document.createElement("section");
panel.setAttribute("clay", "no-save no-snapshot no-watch");
panel.innerHTML = `
<form>
<label>Search the saved HTML <input name="query" required></label>
<button>Search</button>
</form>
<pre aria-live="polite"></pre>
`;
document.body.append(panel);
const form = panel.querySelector("form");
const output = panel.querySelector("pre");
const button = panel.querySelector("button");
form.addEventListener("submit", async (event) => {
event.preventDefault();
const query = form.elements.query.value.trim();
if (!query || button.disabled) return;
button.disabled = true;
output.textContent = "Searching";
const request = clay.wire.send({ query }, { document: "none" });
const outcome = await request.done;
output.textContent = outcome.state === "done"
? outcome.result.matches.join("\n") || "No matches"
: outcome.error || outcome.state;
button.disabled = false;
});
});
</script>
</body>
</html>
The wire plugin supplies clay.wire.send. The script builds the search controls each time the page opens. Their clay attribute keeps the controls and results out of saves. document: "none" skips saving the page before searching, so the search reads the saved file without any unsaved page edits.
Save these five lines as search.sh beside the document:
#!/bin/sh
query=$(jq -er '.payload.query | select(type == "string" and length > 0)') || exit 1
matches=$(rg --no-heading --no-filename --color never -F -- "$query" "$HTMLCLAY_WIRE_FILE")
code=$?; [ "$code" -le 1 ] || exit "$code"
jq -cn --arg matches "$matches" '{type:"result",value:{matches:($matches | split("\n") | map(select(length > 0)))}}'
HTML Clay supplies the document’s path in HTMLCLAY_WIRE_FILE. The program reads payload.query from the request. Ripgrep searches for that literal text and returns matching source lines. Exit code 1 means no matches, so the script returns an empty list. Other ripgrep failures stop the program.
Double click todo.htmlclay to open it. In your terminal, change to the folder containing both files. On macOS, first make the app’s command available in that terminal:
alias htmlclay="/Applications/HTMLClay.app/Contents/MacOS/htmlclay"
Skip the alias on Linux. Make the script executable, then attach it:
chmod +x search.sh
htmlclay wire serve todo.htmlclay --protocol=jsonl -- ./search.sh
Leave that terminal running. HTML Clay starts search.sh once per request. --protocol=jsonl tells HTML Clay to read one JSON object per output line. Without that flag, output lines are plain progress text and no JSON result reaches the page.
Type milk and press Search. With the file exactly as shown, the page displays:
<li class="todo" data-done="false">Buy milk</li>
You are seeing a line from the saved file, including its HTML tags. Search for carrots and the page displays No matches.
Let the document name its program#
The same search can run without an open terminal. The document names a program, and you choose which executable that name refers to.
Stop wire serve with Ctrl+C. Add this program name near the start of the document’s <head>:
<meta name="htmlclay-helper" content="todo-search">
Replace the page’s clay.wire.send line with this named request:
const request = clay.wire.send({ query }, { helper: "todo-search" });
Save the file and open it directly again by double clicking it. Opening a document never asks about programs. Instead, HTML Clay shows a bar at the top of the page: “This document wants to run a program called “todo-search”.” Press Set Up “todo-search”… in the bar, or just press the page’s own Search button. Either one opens the setup dialog.
The dialog shows the file that would run first, then the name the document uses for it. Its buttons are Deny, More Options…, and either Allow <file name> when HTML Clay found the program or Choose File… when it did not. None of them is the default, so Return never allows anything. On Windows and Linux the dialog also has Not Now, which is where Return and Escape land.
For todo-search nothing is registered yet, so choose Choose File… and select search.sh. HTML Clay allows it for this document, remembers that across restarts, and the search runs.
HTML Clay looks for the file before it asks. It offers a program you already set up under the same name, or one whose file name matches. It also looks inside the folders of programs you already set up. A page cannot point the search somewhere else: data-program-folder only sets where the file picker opens, so the first program you set up is always one you choose yourself. It never suggests a file from the document’s own folder, Downloads, or a temporary folder. It never suggests a file downloaded from the internet, or one that changed in the last ten minutes. When it skips a file for one of those reasons, the dialog says so. It never suggests a shell or script interpreter such as bash, zsh or python3, because a program receives the page’s request as input and an interpreter would run that request as code. If you choose a file yourself that HTML Clay would not have suggested, it asks you to confirm before using it.
Tell HTML Clay where the program lives with data-program-folder, relative to the document:
<meta name="htmlclay-helper" content="todo-search" data-program-folder="../bin">
A folder that starts with ~/ is relative to your home folder instead, so data-program-folder="~/apps/bin" works from any document. When the file has a different name from the one the document uses, say so with data-program-file:
<meta name="htmlclay-helper" content="search" data-program-folder="~/apps/bin" data-program-file="clay-search">
These hints only help HTML Clay find the file. You still confirm it, and the dialog shows its full path.
More Options… offers Choose Another File… and Allow in Trusted Folders. The second lets every document in your trusted folders that asks for this name run the program without asking. Documents outside your trusted folders still ask, one at a time.
Search for milk again. HTML Clay starts the selected program and returns the same result.
Manage Programs… in the tray’s Programs menu opens the Programs page. It lists every program, which documents may run each one, and a Remove Access button for each. The tray menu also lists open documents with their programs, and any program whose file has gone missing, so you can point it at the file’s new place.
Read the result on the page#
The result becomes available when request.done resolves. For the search above, the program prints this record:
{"type":"result","value":{"matches":[" <li class=\"todo\" data-done=\"false\">Buy milk</li>"]}}
The record’s value becomes outcome.result. Check outcome.state before reading it. The done promise resolves for errors and cancellations too; it never rejects.
Named requests use document: "none" by default, so both attachment methods search the saved file.
A program can also edit the document itself. Use document: "edit" for that request and load the sync plugin alongside wire. ClayJS saves the page before sending the request and holds autosave until the request ends. Agent editing has a complete example. Live updates explains how file changes reach the open page.
Access and limits#
clay.wire.send sends to the page’s own file. A trusted folder lets HTML Clay open every .htmlclay file in it for editing. Any other file in that folder can reach this file’s approved program.
Following a link to a file in a trusted folder does not set up its programs. Double click the file to set up its programs.
document: "none" only skips saving the page before the request. It does not stop a program from writing files.
Each file can have one attached program at a time. Stop a terminal attachment before switching to document programs.
Programs started with --protocol=jsonl have five minutes to finish, regardless of progress. A result record can contain at most 512 KiB, including its JSON wrapper. Keep answers small or divide them into separate requests.
If the search does not run#
- “open it first” or “has never served this file’s folder” in the terminal: open
todo.htmlclaythrough HTML Clay, then attach again. - “no agent is attached to this file” on the page: check that
wire serveis still running. For a document program, check for a missing or misspelled<meta name="htmlclay-helper">tag. - “was not granted that helper” on the page: check the program declaration, then press Set Up in the bar at the top of the page. If you chose Deny, double click the file first.
- “was not set up in time” on the page: the request waited two minutes for setup. Set the program up, then search again.
- The page stays on “Searching” and the Search button stays disabled: stop
wire serve, add--protocol=jsonl, restart the command and reload the page. Reserve the program’s standard output for JSON records. Send diagnostic text to standard error.
For request states, cancellation and the complete output format, read the wire protocol reference. To read or change selected document content from a local program without a page request, use the JSON API.
Registered helper programs#
A document declares helpers in <meta name="htmlclay-helper"> elements near the start of its <head>. HTML Clay reads at most the first 512 KiB and accepts at most eight valid, distinct names. Later declarations are silently ignored.
Opening a document never raises a dialog. A request for a name that is not set up waits, and the page sees the status “Waiting for you to set up todo-search in HTML Clay”. Setup starts in one of three ways: the bar HTML Clay puts at the top of the page, the page’s own button (a click that sends a request for the name), or the document’s row in the tray’s Programs menu. A request that is still waiting after two minutes fails with helper_setup_expired. An allow that lands later is saved, but never runs the old request, so the page sends it again. Several requests for the same name share one dialog. Asking which helpers the page has (wire/describe) never raises it.
The bar shows only the names the document itself declares, never a file or folder. It sits outside the document, so a save never writes it to the file.
After any dialog that granted nothing, the page cannot raise another for one minute. After a Deny, it cannot raise one at all until you open the file directly again. A refusal is never stored. Return and Escape never grant access, and neither do the 120 second timeout, a cancelled file picker, a missing dialog tool, or any dialog error.
A linked .htmlclay file opened inside a trusted folder registers without a prompt. It gets the helpers its existing allows already cover.
There are two kinds of allow:
- Allow (the right button) allows the program for that one document, across reloads and restarts.
- Allow in Trusted Folders (under More Options) allows the program for every document inside your trusted folders that declares the same name. A document outside them still asks.
Remove Access and Remove All Access on the Programs page are remembered: those documents stop asking, and the setup bar no longer appears for them. To give one access again, use its row under Programs → Open Documents in the tray. Turning off a trusted-folders allow only takes the allow away, so those documents offer setup again. The saved decision identifies one concrete program by its local ID, so pointing a moved program at its new file keeps every document that was allowed to use it.
What approval gives the program#
For each request, HTML Clay starts the registered path with the document’s folder as its working directory. It passes the full request as JSON on standard input, inherits the app’s environment, and supplies the document path and request ID in environment variables. On macOS and Linux it also supplies a login shell PATH so ordinary script interpreters can be found.
The five minute execution deadline, the structured output parser, and the result size limits protect HTML Clay from an unbounded request or malformed response. They do not restrict the program’s operating system access. A helper can, among other things:
- Read, create, change, or delete any file your account can access, including files outside the document folder and files HTML Clay itself refuses to serve.
- List directories, start other programs, and leave descendant processes running.
- Use the network and send away anything it can read.
- Read or change HTML Clay’s
config.json, including its program registry and permission decisions. The file is mode 0600, but the helper runs as the same account that owns it.
HTML Clay permits up to eight concurrent helper requests per document. This is not an app wide limit. Several documents can each run eight children, so the limit is not resource isolation.
Register only programs you trust with your account. The security boundary inside a helper is what that program does with hostile standard input. Validate the operation, types, paths, sizes, and every other value before using them. HTML Clay validates the helper’s output protocol. It cannot validate the meaning of the input for the program.
HTML Clay stores the selected program path, not a hash or a pinned file identity. Replacing the program at that path, or changing the target behind a selected symlink, changes what runs without another prompt. Whoever can update that program controls the code future requests execute.
Who can invoke an approved program#
The dispatcher accepts only names declared by that document and allowed in its stored decisions. Helper wire sends and subscriptions also require that document’s save token. Another HTML Clay origin and a local process without the token are refused.
Files in one trusted folder share an origin. A hostile file in that folder can open an approved sibling in a visible top level tab, read the sibling’s save token through their shared origin, and use that token to reach the sibling’s approved helper. Document specific approval therefore does not isolate a helper from hostile files in the same trusted folder.
When a document has a helper dispatcher, both live sync relay addresses refuse page supplied updates to that target, on both relay lanes. This prevents a sibling from silently pushing a script into an already open, helper enabled tab. It does not stop the visible navigation and token path above, and it does not limit the helper after execution starts.
Removing or revoking a program#
Removing a program or its document permissions stops future dispatch. HTML Clay advances the document’s helper generation, rejects late output, and cancels work it is tracking.
That cancellation is not containment. The runner signals only the direct child process and waits for it. Descendants can survive, including descendants that keep output pipes open. Process group cleanup, if added, would be tidying rather than a security boundary because a program running as the user can escape the group or arrange work elsewhere.
Removing or revoking a program does not undo writes, recover data already sent away, or stop work that escaped the tracked process. It also cannot protect the registry from that program, because the registry is owned by the same account.
Removing a program leaves every document decision that pointed at it in place. Each one reads as undecided while the program is gone, so the next open asks again, and restoring the same program ID makes those decisions grant once more. Registering a new program under the same display name does not inherit them: registration mints a new ID, and the stored decisions name the old one.
Let any local program edit the open file#
The wire is a per file channel between an open page and one command you started yourself.
htmlclay wire serve <file> -- <cmd>
Your program reads stdin, prints progress, and exits 0#
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. The command claude -p "$(cat)" works as an AI handler without extra code.
- Page asks — Opaque JSON request
- Program edits — File on disk
- Page updates — Ordinary file change
The wire carries JSON requests and responses. AI editing includes the selected HTML, your request and any included context; your local agent may send that content to its model provider. Requests are capped at 1 MiB.
Built to be trusted with your files#
An attached handler works without an open tab. It keeps watching the file, and edits are still 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 browser cannot act as the 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.
If no program is attached, the page is told right away. The send response reports whether a handler queued the request, so the page cannot mistake its own echo for delivery.
The full protocol is in docs/wire.md.