Building a site people review in ChatGPT's browser? Mark it up so annotations hand Codex the right context

#What changed

On Oct 12, OpenAI Developers showcased browser annotations paired with WebMCP site tools, with a demo by @kagigz that edits scenes and expenses inside ChatGPT's browser. The linked docs describe a JavaScript API at document.oai.annotation, available in the ChatGPT desktop app's built-in browser (DevDay 2026 release and later) on HTTPS or localhost pages.

Annotations already work on any page with no code. The API adds control over what the agent receives:

• Mark a region with oai-annotation-container and items with oai-annotatable="Name" so a whole card or row is selected as one named object.
• Add oai-annotation-container-text to let people drag-select a phrase.
• Attach hidden context with oai-annotation-metadata (flat JSON, up to six properties, 2,048 bytes).
• Open an annotation from your own button with request() and a prefilled comment of up to 240 characters.
• Register up to 12 controls (color, range, select, toggle) that preview a change and record the before and after values.
• Make canvas objects selectable with registerSurface(); its hitTest gets 250 ms before the browser falls back to normal selection.

#Who is affected

Developers and teams who review web apps, design systems, dashboards, or docs in ChatGPT's built-in browser and hand that feedback to Codex or ChatGPT Work. In ChatGPT Enterprise and Edu workspaces, an admin must allow Site annotation customizations in workspace policy first.

#What to do now

1. Feature-detect before showing any annotation button: check that document.oai?.annotation?.request is a function. Ordinary browsers won't have it.
2. Start with the cheap win: wrap cards and table rows in oai-annotation-container and give each oai-annotatable item a distinct name, so Codex gets "Q3 Revenue card" instead of a stray div.
3. Use metadata for IDs the agent needs but the page doesn't show, such as a component name or record ID. Only include what you're fine sharing with both the user and the model.
4. For design-system work, register a range or color control tied to the CSS token (for example reference: "--card-padding"). The annotation then carries the label, token, and old and new values, which is a far tighter instruction than "make it roomier".
5. Call request() and toggle() directly inside the click handler. Awaiting a network call first can lose the user gesture.
6. Expect a difference by surface: the manual Adjust button appears only in Codex or on localhost, while on hosted sites in ChatGPT registered controls show automatically.
7. If you want the agent to act on that feedback, not just read it, add Site tools (WebMCP) as well.

#What is not confirmed

• Neither the post nor the docs measure how much richer annotation context improves Codex's edits; that benefit is our inference.
• The demo is OpenAI's own showcase. DotsFeed has not tested the API in the desktop app.
• The docs only describe the desktop app's built-in browser, so support anywhere else is unknown.

Sources: OpenAI Developers on X and Annotations Extensibility docs.