← screencli  /  docs

Verify with your coding agent

Wire `npx screencli verify` into an AI coding agent's inner loop — Claude Code, Cursor, Cline, Windsurf — so it browser-checks its own change and gets a pass/fail verdict before it opens a PR.

An AI coding agent can edit files, run commands, and open a PR — but a diff and a green test suite don't tell you whether the change actually works in a browser. npx screencli verify closes that gap: after the agent makes a change, it points screencli at the running app, names the behavior that must hold, and gets back a pass / fail / inconclusive verdict plus a recording — the same result the GitHub App posts on a PR, but in the agent's loop before the PR exists. On a fail the agent has concrete evidence to fix the change and try again.

Any agent that can run a shell command — Claude Code, Cursor, Cline, Windsurf, or your own script — can call it. It's a standard CLI tool; there's nothing agent-specific in the command.

Prerequisites

The inner loop

The pattern is the same for every agent — only how you tell the agent to run the command differs:

  1. The agent makes a change — fixes a bug, adds a feature, edits config.

  2. It starts (or reuses) a running app — a local dev server or a preview URL.

  3. It runs verify with the behavior as the assertion:

    npx screencli verify http://localhost:3000 \
  -p "Add an item to the cart, go to checkout, complete the purchase, confirm the order ID renders"

  4. It reads the verdict. pass → the flow works; move on. fail → the reason and recording show exactly what broke, so the agent fixes it and re-runs. inconclusive → the assertion was too vague or the app was unreachable; sharpen the prompt or check the URL.

  5. It opens the PR once verify passes. If you also run the GitHub App, the PR is verified again automatically against its preview deployment — so the same check gates the change locally and on the PR.

verify runs the same browser engine as record and takes the same <url> -p "<prompt>" shape; the difference is intent — verify is for catching a broken flow in the loop. The -p prompt is the assertion, so name a concrete, observable outcome — a vague prompt comes back inconclusive. See Writing effective prompts for how to phrase it.

Set it up for Claude Code

Install the screencli skill so Claude Code can drive a browser and verify its own work as part of your workflow:

npx skills add usefulagents/screencli --skill screencli

Then, after Claude Code makes a change, ask it to verify — it runs the CLI, reads the verdict, and self-corrects on a failure:

Verify the fix works: start the dev server, then run screencli verify against the checkout flow and confirm the order ID renders. If it fails, fix it and re-run until it passes.

Claude Code launches a real browser through screencli, walks the flow, and returns a shareable link at screencli.sh/v/<id> alongside the verdict — no Playwright scripts to write and no selectors to maintain.

Use it from Cursor, Cline, or Windsurf

There's no plugin to install — verify is a shell command, so any agent that can run one can call it. Give the agent a standing instruction (a Cursor/Windsurf rule, a CLAUDE.md note, or just a follow-up message) so it runs the check on its own:

After you make a UI change, run npx screencli verify <preview-url> -p "<the behavior that must hold>". If the verdict is fail or inconclusive, read the reason, fix the change, and re-run until it passes before opening a PR.

Because the command, the flags, and the verdict format are identical across agents, the same instruction works everywhere.

Example — a full pass/fail loop

An agent has just changed the checkout button. It verifies against the local dev server:

npx screencli verify http://localhost:3000 \
  -p "Click Checkout, fill the test card 4242 4242 4242 4242, submit, and confirm the success page shows an order ID"

A failing run comes back like this — the reason tells the agent exactly what to fix:

✗ fail — Checkout submitted but the success page never rendered; the button
         stayed in a loading state and the console logged a 500 from /api/orders.
  recording → https://screencli.sh/v/a3f2c8e1

The agent fixes the API call and re-runs; on success it gets:

✓ pass — Order ID #10428 rendered on the success page after submit.
  recording → https://screencli.sh/v/b7d21f90

Now it opens the PR with a green local verdict — and the GitHub App re-verifies the same behavior on the preview deployment.

Verify an app that needs login

If the flow requires a signed-in session, add --login so you (or the agent, with a saved session) authenticate first, and --auth <name> to reuse that session on later runs:

npx screencli verify http://localhost:3000 -p "Open the billing page and confirm the current plan shows" --login --auth myapp

See Record an app that needs login for how saved sessions work. (The GitHub App handles login differently — via the repo's Authentication settings — because it runs unattended.)

Run it in CI

To gate a merge on a browser check without the GitHub App, run verify in a workflow. Sign in once locally, grab the long-lived token with npx screencli token, store it as a repository secret, and expose it to the CLI as SCREENCLI_TOKEN:

# .github/workflows/verify.yml
- name: Verify checkout against the preview
  env:
    SCREENCLI_TOKEN: ${{ secrets.SCREENCLI_TOKEN }}
  run: npx screencli verify "$PREVIEW_URL" -p "Complete a checkout and confirm the order ID renders"

The full token + CI setup is in CLI login & API access.

Notes & limits