name: codexqa-jev-browser description: Jev browser automation with indexed actions. Replay YAML/Markdown/API cases, run goal-driven flows, generate cases, and explore sites in a real browser. Use when the user mentions Jev, browser automation, UI automation, E2E replay, test case generation, exploratory crawl, or YAML/MD/API test cases. Not a fork of browser-use/jev-ultrafast.

CodexQA Jev Browser

Drive a real browser through the codexqa-jev-browser CLI (TypeScript). Do not invent CSS/XPath/coordinates or replace the engine with a host browser tool.

Choose a mode

1. Existing YAML, Markdown, or API cases → run
2. Only a natural-language goal → auto or generate
3. Unknown site / coverage → explore

Install once, from this skill directory (the directory that contains package.json and SKILL.md):

npm install

Playwright Chromium is the browser. Do not read another application's browser profile.

Commands

npx codexqa-jev-browser observe <url-or-local-html>
npx codexqa-jev-browser run cases/examples/search-docs.yaml
npx codexqa-jev-browser run cases/examples/search-docs.md
npx codexqa-jev-browser run --from-api https://qa.example.com/cases?suite=smoke
npx codexqa-jev-browser auto --url <url> --goal '<goal>'
npx codexqa-jev-browser generate --url <url> --goal '<goal>' --out generated/case.yaml --md --verify
npx codexqa-jev-browser explore --url <url> --out generated/explore

The browser window is shown by default. Set browser.headless: true to hide it. --headed forces a visible window. --no-screenshots skips images.

Model setup

Do this before live auto / generate --goal. The CLI calls Jev or an OpenAI-compatible API itself. The host Cursor/Codex session model is not the decision model. observe, run, explore, and --decisions do not need a key. Do not stop those commands to ask for one.

Keys live in a .env file, not in the chat. The CLI loads the .env next to this SKILL.md first, then a repo-root .env, and does not override variables already set in the shell.

1. Read that .env (or .env.example if .env is missing). If TYPESAFE_API_KEY or OPENAI_API_KEY is already set, run the command. Do not ask again.
2. If neither key is set, copy .env.example to .env in the skill directory and tell the user to fill that file. Do not ask them to paste a key into the chat. Show this shape:

# Each step: which control, which goal phrase to type, whether the step worked, whether the task is done.
TYPESAFE_API_KEY=
TYPESAFE_MODEL=jev-latest
TYPESAFE_BASE_URL=https://api.typesafe.ai/v1

# Task plan before the browser opens. Also the decision and the done check when TYPESAFE_API_KEY is empty.
OPENAI_API_KEY=
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini
TEXT_MODEL=gpt-4o-mini

3. Prefer Jev when TYPESAFE_API_KEY is set. OPENAI_MODEL is only the planner unless Jev is unset. A third-party gateway is OPENAI_BASE_URL or TYPESAFE_BASE_URL, not a separate product. Set HTTPS_PROXY in the same .env only when that gateway needs a proxy.
4. generate writes the YAML after every successful step. Do not hand-author the case step by step while the run is walking the site.
5. Never write a key into case YAML. Never commit .env.

Optional CLI overrides (never --api-key): --model, --base-url, --config. Model name and gateway may also live in codexqa-jev-browser.config.yaml as ${OPENAI_API_KEY}-style placeholders.

After every run

Open or summarize reports/<run-id>/report.html before concluding. It contains suite totals, every step, and screenshots. Exit code is non-zero on failure. report.json is the machine-readable copy; report.md is the short summary.

Hard rules

• Model output may only choose an operation plus an observed index. Never execute model-written selectors, JS, or shell.
• DONE is not success. Assertions or visible evidence decide the result.
• Secrets stay in environment variables (${PASSWORD}), never in case files.
• Confirm before explore/auto on logout, delete, pay, or other destructive controls.
• Prefer semantic targets: {role, name, nth, within}.

Business knowledge

Per-app notes live in knowledge/<app>/*.md. On live auto / generate --goal, the CLI matches the start URL and the goal against each note's hosts and keywords, then appends the hits to the planner, the decision goal, and the field-text prompt. A note with general: true is included on every run.

Notes are reference for what to type and which visible control to prefer. They do not add operations. Do not copy them into case YAML. Add a new app by adding a note. Do not put that app's fill rules back into src/policy.ts.

Case sources

• YAML is the source of truth. Markdown uses numbered Click/Type/Select/Scroll/Wait/Assert/HTTP lines.
• --from-api pulls cases; steps may also use op: http for setup or backend checks.

Schema and verbs: references/schema.md. Examples: references/examples.md.

CodexQA Jev Browser

简体中文 · How it works · Known limitations

Jev Browser is one skill in CodexQA: local Agent Skills that check whether code is actually good after it is written. This repository is the standalone project. The same skill is also installed from the CodexQA catalog.

GUI-model browser automation sends a screenshot to a vision model on every step. Recognition spends vision tokens, the loop waits for the model to read the image, and the click lands on coordinates.

CodexQA Jev Browser finds controls from an index built inside the page and treats visible page evidence as the result. Replay, goal runs, case generation, and site exploration share that index. The browser is Playwright Chromium. This repository has no benchmark against vision GUI models. The rows below are the structural answers to those costs.

On TypeSafe’s published System One comparison, a Jev decision is 40×–200× faster than a frontier LLM on the same kind of question (70–500 ms, against multi-second LLM calls). Their workflow demo is 193.6× faster and 444.6× cheaper: $0.000081 in 0.114 s versus $0.013880 in 8.566 s. TypeSafe calls that pair the high end of real-world gains. Jev lists input at $0.042 per million tokens, 238× lower than Claude Fable 5.1, and does not bill output tokens. These figures are for the decision call, not for loading the page or saving the report. Source: TypeSafe and the launch post.

What raises the pass rate

The knowledge base is the main lever. Jev only chooses an indexed control, and the characters it can type are phrases already in the goal. It does not know that a Baidu cite is an ad, that the left city box is the departure city, or that a login dialog means stop. Those facts belong in knowledge/<app>/*.md.

A failed live run is usually a missing or wrong note, not a missing selector. Read the report, name the control the model should have used or avoided, and add that sentence to the matching note. hosts matches the site. keywords match the goal. general: true is attached on every run, such as the login-dialog stop. Notes are reference. The model still has to pick an index that was observed. Do not put that site's fill rules into src/policy.ts.

Where traditional automation gets stuck

Highlights

• Closed action space. Observation assigns each visible control an index, a role, a name, and the operations it actually supports. The decision is accepted only when both the operation and the index are in that set. Selector-like text, JavaScript, and shell in the model reply are rejected before anything runs.
• Jev answers structured choices. With TYPESAFE_API_KEY, each step is a /systemone questionnaire: which operation, and which observed target. The same channel judges whether that one action showed up on the next page. An OpenAI-compatible chat/completions call is the fallback decision model. --decisions skips both.
• The browser is Playwright Chromium. Password field values are left out of model requests.
• Generated cases replay without the decision model. YAML, Markdown, and API cases name targets as {role, name, nth, within}. Those fields are resolved against the live index, including controls inside iframes. generate writes that YAML after every successful step. --verify then replays the file through run.
• Visible evidence decides the result. A planner names done_when as something that must be on the page. DONE passes only when that evidence is visible. A failed assertion still runs teardown. The HTML report keeps the marked screenshot, step timing, token use, and the session video.

Architecture

observe, run, explore, and --decisions stop at the index and the actor. Live auto and generate --goal add the planner and a decision provider. generate turns a passing trace back into a case the actor can replay alone.

Typing uses characters the same Jev decision chooses from phrases already in the goal. Which control receives them is still the node id on the index. Notes in knowledge/<app>/ stay on that decision.

Execution report

Each run writes reports/<run-id>/report.html: the case, every step, and the marked screenshot. Open the sample:

Install

npm install
cp .env.example .env   # live auto / generate --goal

Model calls use HTTPS_PROXY only when that variable is set.

Node.js 20 or newer.

Model

The CLI calls Jev or an OpenAI-compatible API itself. The host Cursor or Codex session is not the decision model. Copy .env.example to .env and fill it in. The CLI reads cwd/.env, then the repo-root .env, and does not override variables already set in the shell. Do not commit .env.

# Per-step decision: which control, which goal phrase to type, whether the step worked, whether the task is done.
TYPESAFE_API_KEY=
TYPESAFE_MODEL=jev-latest
TYPESAFE_BASE_URL=https://api.typesafe.ai/v1

# Task plan before the case runs. Also the decision and the done check when TYPESAFE_API_KEY is unset.
OPENAI_API_KEY=
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini
TEXT_MODEL=gpt-4o-mini

Priority for the decision provider: --decisions script, then Jev when TYPESAFE_API_KEY is set, then chat completions. --model and --base-url override the chat model and gateway. codexqa-jev-browser.config.yaml may use ${OPENAI_API_KEY}-style placeholders. Do not pass --api-key or put a raw key in a case file. Set HTTPS_PROXY only if the gateway needs it. The CLI does not probe local proxy ports.

Commands

npx codexqa-jev-browser observe examples/app/index.html
npx codexqa-jev-browser run cases/examples/search-docs.yaml cases/examples/login.yaml
npx codexqa-jev-browser run cases/examples/search-docs.md
npx codexqa-jev-browser run --from-api https://qa.example.com/cases
npx codexqa-jev-browser auto --url examples/app/index.html --goal '搜索 Pilot 并打开文档' \
  --decisions cases/scripts/decisions-search.yaml
npx codexqa-jev-browser generate --url examples/app/index.html --goal '搜索 Pilot 并打开文档' \
  --decisions cases/scripts/decisions-search.yaml --out generated/search.yaml --md --verify
npx codexqa-jev-browser explore --url examples/app/index.html --out generated/explore

The window is visible by default. browser.headless: true hides it. --headed forces a window. --no-screenshots skips images.

Reports land in reports/<run-id>/report.html. report.json is the machine-readable copy. report.md is the short summary. A failing case exits non-zero.

Layout

SKILL.md            Agent entry: when to use this skill and which command to run
bin/                CLI launcher
src/                Runtime. observe/ builds the control index. report/ writes the HTML report
knowledge/          Notes for the decision. general/ applies to every site; other folders are per app
cases/              Replay examples, plus scripted decisions under cases/scripts
examples/app/       Small local HTML pages used by tests and the commands above
references/         Step schema and examples
tests/              Offline checks. They do not call a live site or a live model
agents/openai.yaml  Display name and short description for the Agents surface
docs/jev-browser-overview.en.jpg English product overview at the top of this README
docs/jev-browser-overview.jpg    Chinese product overview, used by README.zh-CN.md
docs/jev-report.png Report screenshot in the Execution report section
reports/            One folder per run. Git ignores it

Part of CodexQA

Browser replay is the UI step. The rest of the check lives in CodexQA: requirements, cases, test data, blast radius, defect scans, and a review page you can open. Install the catalog, or only this skill:

npx skills add openqa-cn/codexqa
npx skills