codexqa-jev-browser

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 c