Work with browsers, screenshots and images

Back to the Codex learning hub

Goal and preparation

Lessons and resources mentioned here: First project

Step 1: Choose a browser surface

Codex desktop can share a page through the built-in browser, opened from the toolbar, a URL or @Browser. The opening shortcut is Cmd+Shift+B on macOS and Ctrl+Shift+B on Windows. On Linux, inspect the actual desktop toolbar and available features rather than assuming every distribution uses the same shortcut. Built-in Browser is unavailable in CLI/IDE; verify a separately configured browser MCP if present, otherwise open the page yourself and attach screenshots.

The built-in browser has separate profile/login state and does not automatically take over regular Chrome/Edge tabs. Follow the official browser-extension connection flow for an existing normal-browser session and record which environment was tested. Site permission permits interaction without making page instructions trustworthy; keep actions within your request instead of uploading unrelated project files or changing permissions at a page's direction.

Step 2: Start and identify the page

Run the reference's three tests from expected, then start a loopback-only static server using the platform command below and leave its terminal open. If 4173 is occupied, choose another free port and update all URLs without stopping another service. This is a local exercise preview, not public deployment.

node --test core.test.mjs

py -m http.server 4173 --bind 127.0.0.1

python3 -m http.server 4173 --bind 127.0.0.1

Open http://127.0.0.1:4173 and verify the heading, New task form and Show filter. Add Build and Read the AGENTS.md rules, then complete Build; expect 1 active/2 total. Profiles can have separate localStorage, so compare before/after in the same profile. For existing data, use an isolated practice profile or another port instead of clearing your everyday browser's storage.

If Codex runs on another host, 127.0.0.1 refers to that host. A hosted web task's localhost is not your computer either. Verify where the app and browser run and use the environment's supported preview/forwarding flow. Mobile Remote can review connected-computer work; this lesson does not expose the practice server to the internet. See Cross-device workflow.

Step 3: Capture and describe the target

Use responsive mode at 390×900 and 1280×900 CSS pixels with fixed zoom and the same two tasks. Capture the page area with Windows Snipping Tool, macOS region capture or the Linux screenshot utility, saving before-390.png and before-1280.png. Device scaling can alter PNG pixel dimensions, so separately record CSS viewport, zoom, browser version and date instead of inferring them from image dimensions.

# Visual check
Route: http://127.0.0.1:4173
Browser / version:
OS / date:
CSS viewport: 390 x 900, then 1280 x 900
Zoom:
State: Build complete; Read the AGENTS.md rules active
Before images:
Requested change: reduce header bottom spacing from 36px to 24px
Preserve: task data, labels, focus outline and control sizes
After images:
Behavior checks:
Unverified platforms:

Remove account areas, private tabs and notifications from the capture, taking a smaller region if needed. Do not relabel another platform's screenshot as a test of your platform. Redact personal data before sharing. Concept/generated images can describe a visual direction when labeled illustrations, but cannot prove an operation. For others' images, preserve source, author, license and attribution, with captions and alt text in the article's language.

Step 4: Annotate one specific change

First open the practice project and a new task in Codex desktop. For the CLI route, run codex from the practice-project folder and start a fresh interactive session. If desktop Annotation mode is available, select the region between heading and form, describe the spacing change and submit a request in the parent task. Otherwise attach the two before images and identify the gap in text. Saving a comment does not itself start a model edit; submit the task. Replace vague aesthetic requests with the desired value, preserved behavior and both viewport checks.

Use the attached before screenshots and the local practice page at http://127.0.0.1:4173.
In style.css, reduce the existing header bottom margin from 36px to 24px.
Keep the task data, labels, responsive form layout, 46px controls and visible focus outline unchanged.
Verify the actual page at 390x900 and 1280x900 CSS pixels with the same two tasks.
Check no horizontal page overflow, usable filtering, keyboard focus and persistence after reload.
Report the file diff and before/after evidence. If the browser is unavailable, identify that limitation instead of claiming visual verification.

header { margin-bottom: 24px; }

The reference edit replaces 36px with 24px in the existing rule instead of appending a duplicate that later CSS might override. Inspect the diff for unrelated changes to core.mjs/app.js or removed focus outlines. Desktop developer mode or browser inspection can check the computed header margin-bottom, providing more specific evidence than visual similarity alone. If unavailable, record the limitation and compare manually.

On your practice page, open browser developer tools and select Console. Confirm the current URL before running this read-only measurement. Record both viewport sizes: headerMarginBottom should change from 36px to 24px. A missing header returns null; verify the page and element instead of treating it as zero or a pass.

(() => {
  const header = document.querySelector('header');
  const page = document.documentElement;
  return {
    url: location.href,
    viewportWidth: page.clientWidth,
    headerMarginBottom: header ? getComputedStyle(header).marginBottom : null,
    horizontalOverflow: page.scrollWidth > page.clientWidth,
  };
})()

Expect horizontalOverflow to be false. It checks page width, not control usability, text readability or visible focus. Still perform the keyboard, long-title and persistence checks below. If Console was unavailable, record no measurement rather than copying expected values as observations. See getComputedStyle and scrollWidth for the value definitions.

Step 5: Verify in the page and restore

Reload and save after images at both viewports. Verify reduced spacing, input, Active showing one task, visible Tab focus and persistence of both original tasks. Add a near-100-character title and check wrapping without page overflow; short labels alone do not cover that boundary. Rerun core.test.mjs and record code tests separately from visual checks.

For unchanged appearance, check URL, server directory, saved CSS, cache and overrides. For a blank page, verify HTTP module loading rather than treating file:// restrictions as a regression. If browser operation is unavailable, report code edits with visual checks pending instead of generating an attractive after image as proof. Restore only the margin to 36px, inspect the diff and reload, then stop your practice server with Ctrl+C.

The record should identify the actual page, both sizes, edited file, tested behavior and untested platforms. Keep reader captures separate from existing reference images and label dates/sources. Built-in browser entry, annotations and permissions are documented from official sources without claiming operation of your account or every platform. Continue to Scheduling and automation.

Back to the Codex learning hub

Read the full description

Reference to Change to Compare

• AI tools
• Tutorials
• Codex