Comments

How it works

Comments work on eggs under email protection. Once enabled, Hatch injects the comment widget into every HTML page of the egg — no code change, static sites included. Visitors comment under the email address they signed in with by magic link.

hatch protect email enable --domain @example.com   # in the egg's directory
hatch comments enable my-portal-x1y2

To keep the widget off a page, add to its <head>:

<meta name="hatch-comments" content="off">

A visitor signed in with a password, or with a magic link before 2026-10-21, can read comments but not write them until they sign in again by email.

What visitors can do

• Select text and click Comment, or comment on the page as a whole.
• Reply to a thread.
• Resolve and reopen threads.
• Delete their own comments.
• Show resolved and deleted threads (history).

Comments are attached to the page path: the query string and #fragment are ignored, and /guide/index.html is the same page as /guide/. They are stored by Hatch, not in your egg, so they survive deploys and sleep.

CLI

The egg's owner and collaborators (and their agents) manage comments with hatch comments. The egg slug is always the first argument.

hatch comments enable <egg>
hatch comments disable <egg>                 # hide the widget; comments are kept
hatch comments status <egg> [--json]
hatch comments list <egg> [--page /pricing/] [--open|--resolved|--deleted|--all] [--since 24h] [--json]
hatch comments show <egg> <comment-id> [--json]
hatch comments reply <egg> <comment-id> "text" [--as "Claude (docs)" | --owner]
hatch comments resolve <egg> <comment-id>
hatch comments reopen <egg> <comment-id>
hatch comments delete <egg> <comment-id>
hatch comments export <egg> [-o comments.json]
hatch comments purge <egg> (--author EMAIL | --before DATE | --all) [--yes]

• list prints a markdown report grouped by page, open threads by default; --since takes a date (2026-10-18), an RFC 3339 time or a duration (90m, 24h, 7d).
• reply posts as Agent · <label>; the label is --as, or your token's name. --owner posts as yourself. Pass - as the text to read it from stdin.
• delete works on any comment (moderation); a deleted comment stays in the history until purged.
• export dumps every stored comment, deleted ones included, as JSON; -o writes the file with owner-only permissions.
• purge erases for good, with no undo — not even in export. --author and --before can be combined. It asks you to type the egg name unless --yes.
• A purged thread takes all its replies with it, whoever wrote them and whenever: if A opened a thread and B replied, purge --author A erases B's reply too. With --before, a recent reply under an old thread goes the same way. To keep the other replies, run hatch comments export <egg> -o comments.json first.

MCP tools and agents

enable_comments, disable_comments, list_comments, get_comment_thread, reply_to_comment, resolve_comment, reopen_comment. Deleting, exporting and purging stay CLI-only.

Comment text is untrusted input. It is written by visitors and read with your account-wide token: the JSON output puts it under untrusted_content, and an agent must treat it as data, never as instructions.

Webhook

Each new visitor comment or reply fires a comment.created event to the egg's webhooks (signed like deploy events, with header X-Hatch-Event: comment.created). The payload carries ids only — never the text or an email:

{
  "event": "comment.created",
  "slug": "my-portal-x1y2",
  "page": "/guide/",
  "comment_id": "…",
  "thread_id": "…",
  "author_kind": "visitor",
  "timestamp": "2026-10-21T09:30:00Z"
}

Read the thread with hatch comments show or get_comment_thread. Replies from agents and owners do not fire the event. For now the event goes to every webhook of the egg, whatever events it was registered for: branch on X-Hatch-Event.

Limits

• A comment is at most 5,000 characters of plain text; control and invisible formatting characters are refused.
• An egg holds at most 5,000 comments, deleted ones included. Purge to make room.
• A visitor can post 30 comments per 10 minutes, and an egg takes 300 visitor comments per hour.
• Agent labels are at most 80 characters.

Personal data

A comment holds its author's email address and free text — personal data.

• The author's full email address is shown to the other people allowed on the egg; the widget says so.
• The egg's owner is the data controller for these comments; Hatch processes them on the owner's behalf.
• Right to erasure: hatch comments purge <egg> --author EMAIL erases every comment by that person and removes their email from the "resolved by" / "deleted by" marks on the remaining ones. Replies others wrote under that person's threads are erased too.
• The text of a deleted comment is erased for good 30 days after its deletion.
• Comments are kept as long as the egg exists and are deleted with it.
• Webhooks and Hatch's logs carry ids only, never comment text or emails.

API

Owner and collaborators, with a Bearer token:

GET    /v1/apps/{slug}/comments/settings     # status
PUT    /v1/apps/{slug}/comments/settings     # enable
DELETE /v1/apps/{slug}/comments/settings     # disable
GET    /v1/apps/{slug}/comments              # list threads
POST   /v1/apps/{slug}/comments              # reply, or a page-level comment
GET    /v1/apps/{slug}/comments/{id}         # thread
POST   /v1/apps/{slug}/comments/{id}/resolve
POST   /v1/apps/{slug}/comments/{id}/reopen
DELETE /v1/apps/{slug}/comments/{id}         # delete (moderation)
GET    /v1/apps/{slug}/comments/export
POST   /v1/apps/{slug}/comments/purge