# Programs and helpers

> Let local programs and helper scripts edit your documents through the wire endpoints.

Source: https://hyperclaylocal.com/docs/programs/

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](https://clayjs.com/docs/plugins/wire/) and [The wire protocol](https://clayjs.com/docs/wire-protocol/). For command-line tools and helper setup, see [Document programs](https://htmlclay.com/docs/programs/) and [The wire CLI](https://htmlclay.com/docs/wire-cli/).

## Wire endpoints

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

```http
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](https://hyperclaylocal.com/docs/rejected/)).

## 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](https://hyperclaylocal.com/docs/files/)). That file records the process ID, timestamp, and the real path and port of each running folder:

```json
{
  "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](https://htmlclay.com/docs/wire-cli/) and [Folders and ports](https://hyperclaylocal.com/docs/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](https://hyperclaylocal.com/docs/guide/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.