Hyperclay Local
  1. Hyperclay Local
  2. Guide
  3. AI editing

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.

On any editable document served by Hyperclay Local that loads ClayJS, 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.
  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).

To turn it off or back on:

  • Open the 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 and Settings and profile):

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.