AI editing

Select the sentence "Visitors arriving late will not be admitted" and ask your agent to make it friendlier. The paragraph might now read "Please arrive on time, as we're unable to admit late arrivals". The rewrite stays unsaved until you click Keep.

ClayJS sends the paragraph around your selection and your request to your agent through HTML Clay or Hyperclay Local. The agent returns revised HTML. ClayJS shows the rewrite on the page. Keep saves the rewrite into the file.

Before you start

You need HTML Clay or Hyperclay Local, a file that loads ClayJS with AI editing turned on, and Claude Code installed and signed in on your computer.

Add ai-edit to the plugins in the ClayJS script tag. The tag from Get started becomes:

<script src="https://clayjs.com/v1/clay.js?plugins=indicator,ai-edit"></script>

Open the file through the app. The app does not add the tag for you. The text needs no special markup or ids.

The request holds your words, the element containing your selection and any files you attach. Adding @page includes the whole saved page. Your agent sends all of it to its model provider. The app sends this content nowhere else.

Rewrite a paragraph

The rewrite replaces the original paragraph on the page. You can read it before deciding whether to save it.

1. Select the sentence you want changed, such as "Visitors arriving late will not be admitted". Keep the selection inside one paragraph.
2. Press ⌘J on macOS or Ctrl+J on Windows and Linux. You can also click the small AI chip at the end of the selection. The selected words stay highlighted. A panel opens under them with one box and a Send button. Escape closes the panel.
3. In the "Describe the change" box, type "Make this friendlier. Keep the rule that late arrivals cannot enter". Shift+Enter adds a line to your request.
4. Press Enter or click Send. Send becomes Stop. A status line below the box shows progress, such as "Writing, 1.2 KB". Stop or Escape cancels the request and restores the original paragraph. When the reply arrives, the rewrite replaces the paragraph. Revert and Keep appear, and the status line names the model that answered.
5. Check that the rewrite still says what you mean. Revert restores the original paragraph. Escape also discards the rewrite. Click Keep to save the rewrite into the file. Check the status line for a save confirmation or an error.

Every save waits while you review the rewrite, including autosave and ⌘S. Revert runs any waiting save with the original paragraph back. Keep saves the rewrite instead.

After Keep, open the file in your text editor. If you kept the example rewrite, the paragraph now contains:

<p>Please arrive on time, as we're unable to admit late arrivals.</p>

The earlier version is in Backups in HTML Clay's tray menu. Hyperclay Local keeps earlier versions in .hyperclay/versions/ inside the served folder.

Choose an agent

Claude Code handles requests by default. To use Fable through Claude Code, start your request with @fable:

@fable Make this friendlier. Keep the rule that late arrivals cannot enter.

Use @codex instead for Codex. The Codex CLI must be installed and signed in on your computer. Its status line stays on "sending…" until the reply arrives, then reads done (codex).

What the agent sees

The agent receives the paragraph's HTML, your selected words and your request. Selecting inside a heading sends the heading. On plain pages, selecting inside a list item or table cell sends that item or cell. Inside a section marked with data-edit-id, a list item or table cell sends the whole section instead.

A selection across two paragraphs sends their surrounding element. The agent can rewrite everything inside that element. If only the page's body contains both paragraphs, the agent receives the whole body, with your selected words quoted.

When the whole body is sent, leave the rest of the page alone until you click Keep or Revert. Edits made elsewhere in the body meanwhile are lost however the request ends.

For a paragraph request, adding @page saves the file first, then sends the whole saved page as context. When the whole body is already sent, @page saves nothing and adds nothing.

Adding @name.ext attaches that file from the document's folder as context. In Hyperclay Local, attachments come from the served folder. Hidden files and folders, such as .env or .git, cannot be attached. Symlinks cannot bypass that rule or reach outside the folder. You can attach up to 8 files, at most 256 KB each and 1 MB total.

Claude Code, Fable and Codex run with no tools. They answer in one reply. They can only return text. An agent command you add yourself runs as you wrote it, in the file's folder. ClayJS checks the reply before showing it. A reply that adds an executable script, an event handler or a javascript: link is refused.

Turn off AI editing

Uncheck "AI Editing" in HTML Clay's tray menu to turn it off. In Hyperclay Local, the same setting is in Options.

To turn it off for one file, remove ai-edit from the plugins= list in the ClayJS script tag. Save the file and reload the page.

When it does not work

1. If the status line says an agent was not found or is not signed in, install or sign in to the agent you asked for (Claude Code unless you typed @fable or @codex). Then send again.
2. Unknown @name: the panel lists the agents it knows. Remove the name to use Claude Code, or use @fable or @codex.
3. AI editing is turned off, with no Send button: enable "AI Editing" in the app's menu.
4. The shortcut does something else or nothing: select some text first. If the browser keeps the shortcut, click the AI chip. If no chip appears, check that the file is open through the app and AI editing is on.
5. Another request is running: wait for it to finish. Each file handles one request at a time.
6. Reply refused for adding code: the original stays in place. Ask again without the code, or add code by editing the file.
7. "reply is not a single" element or "the model declined this request": revise the request and send again.
8. The selected element is too large: select text inside a smaller element. Selecting fewer words inside the same element does not help. If that single element is too large, edit it in the file.
9. A request runs for five minutes: it stops and restores the original paragraph. For a whole body request, the recovery rule above applies to the whole body.
10. Attachment refused: check the status line against the attachment limits above. A missing or hidden file stops the whole request. So does a file outside the folder or over a limit.
11. Keep reports a save error: try saving the page again. Copy the rewrite before reloading or closing the page. The rewrite being visible does not confirm a save.

Where next

For an agent restructuring a whole page by editing the file directly, see live updates. Programs covers connecting a page to a program on your computer. The JSON API lets programs read and change parts of the document as JSON. Find the other guides in the docs.