dev-browser

• Local/source-available sites: Read the source code first to write selectors directly
• Unknown page layouts: Use getAISnapshot() to discover elements and selectSnapshotRef() to interact with them
• Visual feedback: Take screenshots to see what the user sees

Two modes available. Ask the user if unclear which to use.

Standalone Mode (Default)

Launches a new Chromium browser for fresh automation sessions.

```bash

cd ~/.codex/skills/browser/dev-browser && ./server.sh &

```

Add --headless flag if user requests it. Wait for the Ready message before running scripts.

Extension Mode

Connects to user's existing Chrome browser. Use this when:

• The user is already logged into sites and wants you to do things behind an authed experience that isn't local dev.
• The user asks you to use the extension

Important: The core flow is still the same. You create named pages inside of their browser.

Start the relay server:

```bash

cd ~/.codex/skills/browser/dev-browser && npm i && npm run start-extension &

```

Wait for Waiting for extension to connect...

Workflow:

1. Scripts call client.page("name") just like the normal mode to create new pages / connect to existing ones.
2. Automation runs on the user's actual browser session

If the extension hasn't connected yet, tell the user to launch and activate it. Download link: https://github.com/SawyerHood/dev-browser/releases

> Run all scripts from ~/.codex/skills/browser/dev-browser/ directory. The @/ import alias requires this directory's config.

Execute scripts inline using heredocs:

```bash

cd ~/.codex/skills/browser/dev-browser && npx tsx <<'EOF'

import { connect, waitForPageLoad } from "@/client.js";

const client = await connect();

const page = await client.page("example"); // descriptive name like "cnn-homepage"

await page.setViewportSize({ width: 1280, height: 800 });

await page.goto("https://example.com");

await waitForPageLoad(page);

console.log({ title: await page.title(), url: page.url() });

await client.disconnect();

EOF

```

Write to tmp/ files only when the script needs reuse, is complex, or user explicitly requests it.

Key Principles

1. Small scripts: Each script does ONE thing (navigate, click, fill, check)
2. Evaluate state: Log/return state at the end to decide next steps
3. Descriptive page names: Use "checkout", "login", not "main"
4. Disconnect to exit: await client.disconnect() - pages persist on server
5. Plain JS in evaluate: page.evaluate() runs in browser - no TypeScript syntax

Follow this pattern for complex tasks:

1. Write a script to perform one action
2. Run it and observe the output
3. Evaluate - did it work? What's the current state?
4. Decide - is the task complete or do we need another script?
5. Repeat until task is done

No TypeScript in Browser Context

Code passed to page.evaluate() runs in the browser, which doesn't understand TypeScript:

```typescript

// ✅ Correct: plain JavaScript

const text = await page.evaluate(() => {

return document.body.innerText;

});

// ❌ Wrong: TypeScript syntax will fail at runtime

const text = await page.evaluate(() => {

const el: HTMLElement = document.body; // Type annotation breaks in browser!

return el.innerText;

});

```

For scraping large datasets, intercept and replay network requests rather than scrolling the DOM. See [references/scraping.md](references/scraping.md) for the complete guide covering request capture, schema discovery, and paginated API replay.

```typescript

const client = await connect();

const page = await client.page("name"); // Get or create named page

const pages = await client.list(); // List all page names

await client.close("name"); // Close a page

await client.disconnect(); // Disconnect (pages persist)

// ARIA Snapshot methods

const snapshot = await client.getAISnapshot("name"); // Get accessibility tree

const element = await client.selectSnapshotRef("name", "e5"); // Get element by ref

```

The page object is a standard Playwright Page.

```typescript

import { waitForPageLoad } from "@/client.js";

await waitForPageLoad(page); // After navigation

await page.waitForSelector(".results"); // For specific elements

await page.waitForURL("**/success"); // For specific URL

```

Screenshots

```typescript

await page.screenshot({ path: "tmp/screenshot.png" });

await page.screenshot({ path: "tmp/full.png", fullPage: true });

```

ARIA Snapshot (Element Discovery)

Use getAISnapshot() to discover page elements. Returns YAML-formatted accessibility tree:

```yaml

• banner:

- link "Hacker News" [ref=e1]

- navigation:

- link "new" [ref=e2]

• main:

- list:

- listitem:

- link "Article Title" [ref=e8]

- link "328 comments" [ref=e9]

• contentinfo:

- textbox [ref=e10]

- /placeholder: "Search"

```

Interpreting refs:

• [ref=eN] - Element reference for interaction (visible, clickable elements only)
• [checked], [disabled], [expanded] - Element states
• [level=N] - Heading level
• /url:, /placeholder: - Element properties

Interacting with refs:

```typescript

const snapshot = await client.getAISnapshot("hackernews");

console.log(snapshot); // Find the ref you need

const element = await client.selectSnapshotRef("hackernews", "e2");

await element.click();

```

Page state persists after failures. Debug with:

```bash

cd ~/.codex/skills/browser/dev-browser && npx tsx <<'EOF'

import { connect } from "@/client.js";

const client = await connect();

const page = await client.page("hackernews");

await page.screenshot({ path: "tmp/debug.png" });

console.log({

url: page.url(),

title: await page.title(),

bodyText: await page.textContent("body").then((t) => t?.slice(0, 200)),

});

await client.disconnect();

EOF

```