Programs and helpers

A document served by Hyperclay Local can ask a program on your computer to edit the file it is running from, then watch the change arrive the same way any other file change does. No HTML travels on the wire in either direction. The file on disk is the only thing the two sides share.

For building documents that talk to local programs, see the ClayJS wire plugin and The wire protocol. For command-line tools and helper setup, see Document programs and The wire CLI.

Wire endpoints#

Every served folder exposes two loopback routes under the /_/ prefix:

GET  /_/wire/subscribe?file=notes.htmlclay   (Server-Sent Events; the program side adds ?role=handler)
POST /_/wire/send                            {"v","type","id","file","text","payload"}

• GET /_/wire/subscribe?file=<name> opens a Server-Sent Events stream for that file. The document subscribes with the file parameter, and the local handler program adds ?role=handler.
• POST /_/wire/send sends a JSON frame with fields v, type, id, file, text, and payload.
• Every frame’s type starts with wire/, and each request ends with one terminal frame (wire/done or wire/error).

Both routes require the /_/ prefix, so a user folder named wire is still served as a normal folder. Both routes also refuse any request with a non-loopback Host header (see Rejected requests).

Port discovery for scripts#

Because Hyperclay Local can serve your personal folder on port 4321 and team folders on their own ports, it writes served-roots.json in the app data directory while folders are running (see Files the app writes). That file records the process ID, timestamp, and the real path and port of each running folder:

{
  "v": 1,
  "pid": 12345,
  "updatedAt": 1761336000000,
  "roots": [
    { "path": "/Users/you/hyperclay", "port": 4321 }
  ]
}

The htmlclay wire command reads this file to find a folder’s port automatically, even if you move a team folder to a new port (see The wire CLI and Folders and ports).

Manage helper permissions#

You can manage registered helper programs and document permissions from the popover’s Options menu:

• Open Options > Helper Programs to view registered programs and click Remove next to any program you want to remove.
• Click Forget All Document Permissions in Options > Helper Programs to clear saved document approvals.
• Built-in AI editing runs through the built-in ai-edit helper without separate program registration, and can be toggled with Options > AI Editing or Enable AI Editing and Disable AI Editing in the tray menu.