How to build a self-verifying browser agent with Claude Code and MegaIndex Browser API

The missing layer in AI browser development

Updated the login flow. Improved selector handling. Added retries. All tests pass.

• only mocked HTML was tested;
• the real website returned a login page;
• the browser opened with the wrong profile;
• the proxy configuration was ignored;
• the expected element existed but was not visible;
• the extractor returned incomplete records;
• the browser session remained open after failure;
• a test was weakened to accept the new behavior.

Claude may decide how to fix the workflow, but it should not decide whether the workflow passed.

Define a browser contract before writing code

• the starting URL;
• the browser profile to use;
• whether a custom proxy is required;
• the page state that confirms successful navigation;
• the interaction sequence;
• the expected output schema;
• the minimum acceptable result;
• the cleanup behavior;
• the evidence that must be saved.

Browser scenario: authenticated product extraction Input: - target URL; - optional profile ID; - optional custom proxy; - expected account name. Success conditions: - BrowserAPI connection is established. - The target URL opens without returning to the login page. - The expected account name is visible. - At least five product cards are found. - Every product contains title, URL, price, and identifier. - A screenshot and JSON result are saved. - The browser session closes after success or failure. Failure conditions: - login page detected; - challenge page detected; - expected account missing; - product count below five; - required product field missing; - browser session not closed.

Separate implementation from acceptance

src/ ├── browser/ │ ├── connect-browser.js │ ├── create-session.js │ └── close-session.js ├── workflows/ │ └── collect-products.js ├── validation/ │ └── validate-products.js └── artifacts/ └── save-run-artifacts.js scripts/ └── verify-product-workflow.mjs

• a login page;
• an access-denied page;
• a regional redirect;
• an empty search result;
• a challenge page;
• a partially rendered application shell.

Connect the verification script to MegaIndex BrowserAPI

npm install --save-dev playwright-core

import fs from "node:fs/promises"; import process from "node:process"; import { chromium } from "playwright-core"; const browserEndpoint = process.env.MEGAINDEX_BROWSER_WS_ENDPOINT; const targetUrl = process.env.BROWSER_TEST_URL; const expectedAccount = process.env.BROWSER_EXPECTED_ACCOUNT; const artifactDirectory = process.env.BROWSER_ARTIFACT_DIRECTORY ?? "artifacts"; const minimumProducts = Number.parseInt( process.env.BROWSER_MINIMUM_PRODUCTS ?? "5", 10, ); if (!browserEndpoint) { throw new Error( "MEGAINDEX_BROWSER_WS_ENDPOINT is required", ); } if (!targetUrl) { throw new Error( "BROWSER_TEST_URL is required", ); } if (!expectedAccount) { throw new Error( "BROWSER_EXPECTED_ACCOUNT is required", ); } if ( !Number.isInteger(minimumProducts) || minimumProducts < 1 ) { throw new Error( "BROWSER_MINIMUM_PRODUCTS must be a positive integer", ); } await fs.mkdir(artifactDirectory, { recursive: true, }); const resultPath = `${artifactDirectory}/browser-result.json`; const screenshotPath = `${artifactDirectory}/browser-page.png`; const pageHtmlPath = `${artifactDirectory}/browser-page.html`; let browser; let page; const startedAt = new Date().toISOString(); try { browser = await chromium.connectOverCDP( browserEndpoint, ); const context = browser.contexts()[0] ?? await browser.newContext(); page = context.pages()[0] ?? await context.newPage(); const response = await page.goto( targetUrl, { waitUntil: "domcontentloaded", timeout: 60000, }, ); if (!response) { throw new Error( "Navigation returned no HTTP response", ); } if (!response.ok()) { throw new Error( `Navigation failed with HTTP status ${response.status()}`, ); } await page .locator("[data-account-name]") .waitFor({ state: "visible", timeout: 30000, }); const accountName = ( await page .locator("[data-account-name]") .first() .textContent() )?.trim() ?? ""; if (accountName !== expectedAccount) { throw new Error( `Unexpected account. Expected "${expectedAccount}", received "${accountName}"`, ); } const loginFormVisible = await page .locator( "form[action*='login'], input[type='password']", ) .first() .isVisible() .catch(() => false); if (loginFormVisible) { throw new Error( "The browser was redirected to a login page", ); } const challengeVisible = await page .locator( "[data-captcha], iframe[src*='captcha'], iframe[src*='challenge']", ) .first() .isVisible() .catch(() => false); if (challengeVisible) { throw new Error( "A challenge page was detected instead of the target content", ); } const products = await page .locator("[data-product]") .evaluateAll((elements) => elements.map((element) => ({ title: element .querySelector("[data-title]") ?.textContent ?.trim() ?? "", price: element .querySelector("[data-price]") ?.textContent ?.trim() ?? "", url: element .querySelector("a") ?.href ?? "", id: element.getAttribute( "data-product-id", ) ?? "", })), ); if (products.length < minimumProducts) { throw new Error( `Expected at least ${minimumProducts} products, received ${products.length}`, ); } const invalidProduct = products.find( (product) => !product.title || !product.price || !product.url || !product.id, ); if (invalidProduct) { throw new Error( `Invalid product record: ${JSON.stringify(invalidProduct)}`, ); } await page.screenshot({ path: screenshotPath, fullPage: true, }); await fs.writeFile( pageHtmlPath, await page.content(), "utf8", ); const result = { passed: true, startedAt, finishedAt: new Date().toISOString(), requestedUrl: targetUrl, finalUrl: page.url(), title: await page.title(), httpStatus: response.status(), accountName, productCount: products.length, products, artifacts: { screenshotPath, pageHtmlPath, }, }; await fs.writeFile( resultPath, `${JSON.stringify(result, null, 2)}\n`, "utf8", ); console.log( JSON.stringify(result), ); } catch (error) { if (page) { await page .screenshot({ path: screenshotPath, fullPage: true, }) .catch(() => undefined); await fs .writeFile( pageHtmlPath, await page.content(), "utf8", ) .catch(() => undefined); } const result = { passed: false, startedAt, finishedAt: new Date().toISOString(), error: error instanceof Error ? error.message : String(error), finalUrl: page?.url() ?? null, artifacts: { screenshotPath, pageHtmlPath, }, }; await fs.writeFile( resultPath, `${JSON.stringify(result, null, 2)}\n`, "utf8", ); console.error( JSON.stringify(result), ); process.exitCode = 1; } finally { await browser ?.close() .catch(() => undefined); }

• the HTTP response;
• the authenticated account;
• the absence of a login form;
• the absence of an obvious challenge page;
• the minimum number of results;
• the required fields in each record;
• the screenshot;
• the saved HTML;
• browser cleanup.

Save evidence, not just logs

Selector timeout after 30000 ms

• the final URL;
• the screenshot;
• the saved HTML;
• the failed request;
• the page title;
• the account state;
• the extracted result.

Classify failures before asking Claude to fix them

• the wrong account is open;
• the selector targets the wrong element;
• a challenge page is present;
• the output schema is invalid;
• an action may create duplicate records.

Create a verification skill for browser changes

.claude/skills/verify-browser-workflow/SKILL.md

--- name: verify-browser-workflow description: Use after changes to MegaIndex BrowserAPI connections, Playwright or Puppeteer navigation, browser profiles, proxies, sessions, selectors, extraction, retries, or browser tests. --- # Verify the browser workflow 1. Read the current git diff. 2. Identify the affected browser scenarios. 3. Check whether browser ownership, profile selection, proxy precedence, or cleanup changed. 4. Run unit tests, linting, and type checking. 5. Run the affected scenario through MegaIndex BrowserAPI. 6. Inspect the JSON result, screenshot, and saved HTML. 7. Confirm: - the expected page was reached; - authentication state is correct; - no challenge or login page was accepted as valid content; - extracted records satisfy the output contract; - the browser session closed; - no test was skipped, deleted, or weakened. 8. Report the commands, exit codes, artifacts, changed tests, and final result.

Block completion with a Stop hook

.claude/hooks/verify-browser-before-stop.sh

#!/usr/bin/env bash set -uo pipefail FAILED=0 run_check() { local name="$1" shift echo "Running ${name}..." if "$@"; then echo "${name}: passed" else echo "${name}: failed" >&2 FAILED=1 fi } run_check \ "unit tests" \ npm test run_check \ "lint" \ npm run lint run_check \ "type checking" \ npm run typecheck run_check \ "MegaIndex BrowserAPI verification" \ npm run verify:browser if [[ "$FAILED" -ne 0 ]]; then echo "Browser acceptance checks failed. Inspect the artifacts and continue working." >&2 exit 2 fi echo "All browser acceptance checks passed." exit 0

.claude/settings.json

{ "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/verify-browser-before-stop.sh", "timeout": 600 } ] } ] } }

Keep the BrowserAPI rules narrow

# MegaIndex BrowserAPI project rules - Reuse the existing BrowserAPI connection module. - Read connection details only from environment variables. - Never print or commit WebSocket credentials, cookies, tokens, or proxy passwords. - Keep browser session ownership explicit. - Close every remote browser session after success or failure. - A custom proxy overrides the proxy assigned to the selected profile. - Do not retry actions that may create duplicate external effects. - Do not replace event-based waits with fixed delays. - Do not accept login, challenge, or error pages as valid target content. - Do not skip, delete, or weaken tests to make a workflow pass. - Browser changes are complete only after remote verification succeeds.

Add a cold review after the implementation passes

Review the current diff as an independent browser automation reviewer. Do not modify files. Check: 1. MegaIndex BrowserAPI connection ownership. 2. Browser cleanup after success and failure. 3. Profile and custom proxy precedence. 4. Authentication state validation. 5. Retry limits and non-idempotent actions. 6. Login, challenge, and error page detection. 7. Extraction validation. 8. Test changes that weaken existing guarantees. 9. Credential exposure. 10. Whether the saved evidence proves the browser contract. Return only concrete findings with file paths and reasons.

• authentication;
• payments;
• account modifications;
• large extraction workflows;
• session reuse;
• proxy routing;
• multiple target websites.

Use structured output in CI

set -euo pipefail npm test npm run lint npm run typecheck npm run verify:browser

claude -p \ --permission-mode plan \ --output-format json \ --max-turns 5 \ "Review the current diff for BrowserAPI regressions. Check session ownership, cleanup, profile and proxy precedence, authentication validation, retry behavior, extraction assertions, test weakening, secret exposure, and the generated verification artifacts." \ > artifacts/claude-browser-review.json

Recommended repository layout

project/ ├── CLAUDE.md ├── .claude/ │ ├── settings.json │ ├── hooks/ │ │ └── verify-browser-before-stop.sh │ └── skills/ │ └── verify-browser-workflow/ │ ├── SKILL.md │ └── reference.md ├── scripts/ │ └── verify-product-workflow.mjs ├── src/ │ ├── browser/ │ ├── workflows/ │ ├── validation/ │ └── artifacts/ ├── tests/ ├── artifacts/ └── package.json

• CLAUDE.md contains permanent constraints.
• Skills describe repeatable browser procedures.
• Hooks enforce acceptance checks.
• Browser scripts run real scenarios through MegaIndex BrowserAPI.
• Artifacts preserve evidence for Claude and human review.
• Tests validate local behavior and browser contracts.

Prompt for creating the self-verifying setup

Inspect this repository and create a self-verifying workflow for its MegaIndex BrowserAPI automation. Do not expose credentials. 1. Identify the existing BrowserAPI connection, session ownership, profile, proxy, extraction, and cleanup code. 2. Define the browser acceptance contract for the primary workflow: - required input; - expected authenticated state; - expected page state; - minimum output; - required output fields; - failure conditions; - cleanup requirements; - artifacts to save. 3. Create a verification script that: - reads the BrowserAPI endpoint from the environment; - connects over CDP; - runs the primary workflow; - rejects login, challenge, and error pages; - validates the extracted output; - saves JSON, screenshot, and HTML artifacts; - closes the browser after success or failure; - exits non-zero when the contract is not satisfied. 4. Create a Claude Code verification skill for changes affecting: - BrowserAPI connections; - sessions; - profiles; - proxies; - navigation; - selectors; - extraction; - retries; - browser tests. 5. Create a Stop hook that runs: - unit tests; - lint; - type checking; - BrowserAPI verification. The hook must exit with code 2 when any required check fails. 6. Audit the current diff and confirm: - no test was deleted, skipped, or weakened; - no credential can appear in logs; - browser cleanup occurs on every path; - retries cannot repeat non-idempotent actions. Return: - browser contract; - files changed; - commands executed; - artifacts produced; - verification result; - unresolved risks.

What changes after this setup

Define the browser contract ↓ Let Claude implement the change ↓ Run the scenario through MegaIndex BrowserAPI ↓ Collect JSON, screenshot, HTML, and test results ↓ Feed failures back to Claude ↓ Block completion until every required check passes ↓ Review the final diff from a fresh context