# AI editing

> Select text on an editable document and press Cmd+J or Ctrl+J to have a local AI CLI agent rewrite that section in place.

Source: https://hyperclaylocal.com/docs/guide/ai-editing/

On any editable document served by Hyperclay Local that loads [ClayJS](https://clayjs.com/docs/plugins/ai-edit/), you can select part of the page, describe a change, and have a command-line AI agent installed on your computer rewrite that section in place.

## What you need

AI editing runs the agent CLI you already have installed and signed in on your computer:

- **Claude Code** (`claude`, used by default, running `claude-opus-5-5`).
- **Codex** (`codex`, used automatically if `claude` is not installed).
- **Fable** (when requested with `@fable`, running `claude-fable-5-1`).

You do not enter an AI API key in Hyperclay Local; the app uses your existing CLI sign-in. If neither Claude Code nor Codex is installed, the panel shows **Neither Claude Code nor Codex is installed. Install one and sign in.**

## Rewrite a section on the page

1. Open your document in [edit mode](https://clayjs.com/docs/edit-mode/).
2. Select the text or section you want to change and click the **AI** chip at the end of the selection (tooltip **Comment on this (⌘J)**), or press `Cmd+J` on macOS (`Ctrl+J` on Windows and Linux). You can also click the page bubble (**Comment on the whole page**).
3. In the **Describe the change** box, type your instruction and press `Enter` or click **Send** (`Shift+Enter` adds a line).
4. While the agent works, a bar shows **Sending…** and **Writing, `<size>`** with a **Stop** button. Clicking **Stop** terminates the agent process immediately.
5. When the reply finishes, the page morphs the new HTML into place and the bar shows **Edit ready.** alongside the model name, **Keep**, and **Revert**. Nothing is written to disk while the rewrite waits for your decision.
6. Click **Keep** to save the change to disk (**Saving…**, then **Saved**), or click **Revert** to restore the original markup. The entire rewrite is a single undoable step.

## Pick an agent or attach file context

Inside the **Describe the change** box, you can use `@` prefixes in your prompt:

- **Pick an agent**: start your comment with `@claude`, `@fable`, or `@codex` to use that agent for the edit. When you name `@claude` or `@fable` explicitly, Hyperclay Local does not switch to another agent if that CLI is missing (`@claude isn't available: 'claude' was not found on this machine. Install it and sign in, or pick another agent with @claude, @fable or @codex.`). `@agy` is refused as unsupported because `agy` can read files without asking and has no switch to disable tools.
- **Attach files from the folder**: name any file inside the served folder with `@file.ext` (for example, `@notes.md` or `@data/items.json`) to include its contents in the prompt. You can attach up to 8 files, at most 256 KB each and 1 MB in total. Hidden files, hidden folders, and symlinks pointing outside the served folder are refused.
- **Attach the whole page**: include `@page` in your prompt to send the full saved HTML of the current document as context.

## Safety and limits

- **No tools or filesystem access**: every built-in agent runs with tools turned off so it cannot read files on your computer, run shell commands, or browse the web. Claude Code runs in an empty scratch folder with `--tools '' --strict-mcp-config --max-turns 1` so MCP servers from your personal Claude configuration are not loaded. Codex runs in a read-only sandbox with shell and tool features disabled.
- **Content only, no code**: the agent is instructed to preserve the attributes of the element it rewrites, and any reply that adds a `<script>` tag, an inline event handler, or a `javascript:` URL is refused with **The reply adds a script or event handler, so it was not applied. AI editing changes content, not code.**
- **Size and concurrency limits**: a selection larger than 900 KB is refused with **This section is too large for AI editing; select a smaller part.** Only one AI edit can run per document at a time, and a run times out after 5 minutes.

## Turn AI editing off or on

AI editing is on by default for every served document (see [Programs and helpers](https://hyperclaylocal.com/docs/programs/)).

To turn it off or back on:

- Open the [popover](https://hyperclaylocal.com/docs/popover/), click **Options**, and toggle **AI Editing**, or
- Right-click the system tray icon and click **Disable AI Editing** / **Enable AI Editing**.

When turned off, opening the comment box on a page shows **AI editing is turned off. Turn it on from the app's menu.** and disables **Send**.

## Configure custom agents

You can register your own command-line agents in `settings.json` inside the app's data folder (see [Files the app writes](https://hyperclaylocal.com/docs/files/) and [Settings and profile](https://hyperclaylocal.com/docs/settings/)):

```json
{
  "aiEdit": {
    "default": "my-agent",
    "engines": {
      "my-agent": ["my-cli", "--prompt", "{prompt}"]
    }
  }
}
```

If an argument in the command array contains `{prompt}`, Hyperclay Local substitutes the prompt into that argument; otherwise, it passes the prompt on standard input. Setting `"default"` makes that agent the default when no `@agent` prefix is typed.