How to Annotate Screenshots for OpenAI Codex

Codex can take images and paths. It cannot read your mind about which of five similar buttons is wrong. Annotation turns a screenshot into instructions.

Vision models interpret pixels; they do not magically know your priority. On a dense settings page, three toggles can look identical at a glance. A number badge and a one-line note remove the coin flip.

A fast path that stays local and works with Codex CLI or any Codex surface that accepts an image or path:

• Open the UI state you want fixed (right theme, breakpoint, and data).
• Hotkey Casso and drag numbered boxes over each region.
• Add a short note per box: what is wrong and what good looks like.
• Send. Copy the prompt into Codex with the annotated image.
• Ask Codex to change only the referenced regions unless you want a broader pass.
• Re-run the UI, re-annotate only remaining issues, and iterate.

Lead with the goal, then the map: "Match spacing of [2] to [1]. Do not change colors." Avoid burying the request after a long story. One issue per region beats a paragraph that mixes five problems.

Add hard constraints when the codebase is large: "Touch only the component that renders [1]. No drive-by refactors." That keeps Codex from rewriting unrelated layout systems.

Pair marks with acceptance checks: "After the change, [1] should have 16px padding and no double border." That turns a visual complaint into a verifiable request.

Casso is not embedded in Codex or Claude Code. You keep one desktop gesture when you hop between them. That is the point of an agent-agnostic layer: the map stays the same; only the paste target changes.

Most failed visual turns share the same mistakes. Avoid these and your first-pass hit rate jumps:

• Huge full-desktop shots with a tiny target and no mark.
• Arrows without numbers when you discuss multiple areas.
• Notes that say "fix this" without expected behavior.
• Uploading sensitive screens to random web tools before the agent.
• Mixing five issues into one box so the model only fixes the first.