Contents
Develop

Annotation Mode

Point at controls in your running application, describe what should change, and hand the result to an AI coding agent.

Annotation Mode is a development-only helper for describing UI changes to a coding agent. While the app runs through npm run dev on macOS or Windows, you can point at a control, write what should change, and get a prompt that includes the annotation text, a selector, the source location when it can be resolved, and an optional screenshot.

Start Annotation Mode 

A development toolbar appears beside the window with Annotation Mode and Developer Tools. You can also start Annotation Mode with Option+Cmd+A on macOS or Ctrl+Shift+A on Windows. Hide or show the toolbar with Option+Cmd+T or Ctrl+Shift+T.

The toolbar and Annotation Mode never appear in packaged applications.

Annotate the interface 

The typical workflow is:

  1. Turn on Annotation Mode and click an element.
  2. Describe the change. Choose whether to include a screenshot, then press Enter.
  3. Repeat for other elements if needed.
  4. Copy the prompt with the toolbar button or Cmd+Enter / Ctrl+Enter, then paste it into your coding agent.

Send annotations to the agent 

When an agent runs the app with npm run dev -- --automation, it can take your annotations directly. Agents in projects created with create-mobrowser-app start listening on their own because AGENTS.md tells them to. While an agent listens, the copy button becomes Send to agent:

  1. Press Send to agent or Cmd+Enter / Ctrl+Enter. The bar shows Waiting for the agent to start.
  2. When the agent takes the annotations, the bar shows Agent is applying the changes. You can’t pick elements until the agent finishes.
  3. When the agent is done, the bar shows Agent finished and Annotation Mode turns off.

If the agent doesn’t take the annotations within 30 seconds, the bar offers Copy instead, so you can paste the prompt into the agent’s chat. This happens with agents that don’t react when a background command finishes. For Codex, MōBrowser posts a message into the session with codex queue when that command is available.

The agent listens with npm run mobrowser -- agent wait-annotations running in the background, gets the prompt with agent take-annotations, and reports that it is done with agent finish-annotations.

The MōBrowser CLI is installed as a local project dependency. Run it through npm as shown in this guide, not as a bare mobrowser command.

To learn how agents launch, inspect, and drive the app, see AI automation.

On this page