Jev Browser

Check setup

Before the first browser task in a conversation, after configuration changes, or when asked to check setup, run:

python3 <skill-dir>/scripts/jev.py doctor

It makes one small Jev API request with synthetic input and checks Chrome through Browser.getVersion; it never reads or changes pages. Report each component's status. If both are ready, proceed with the user's task. Reuse a successful check within the conversation unless a connection/configuration error occurs. Never run this check after a browser result to verify task completion.

Python 3.12+ and uv are required; the launcher installs runtime dependencies. For a Chrome failure, guide the user to open chrome://inspect/#remote-debugging, enable debugging, and allow the connection prompt. Do not restart Chrome. After the user resolves setup, check again and continue their task.

Configure Jev

For a missing API key or an explicit setup request, use local file tools:

• Use JEV_CONFIG_DIR/.env when set, otherwise ~/.config/jev-browser/.env. Inspect only whether TYPESAFE_API_KEY and TYPESAFE_MODEL are configured; never print existing secrets.
• Reuse existing configuration unless the user requests a change. For a missing key, ask the user to provide it through a local file or secret input available in their client. If the user already supplied a key for this setup, write it without echoing it; never recover keys from conversation history.
• Set TYPESAFE_API_KEY to the supplied value and default TYPESAFE_MODEL to jev-latest. Preserve unrelated settings and any existing model unless a change was requested. The file uses literal KEY=value lines without quotes; reject embedded newlines in supplied values.
• Keep the configuration outside the repository, create its directory with mode 700, and write the file with mode 600. Do not put keys in command-line arguments, logs, browser inputs, or replies.
• Process environment variables override the file. After configuration, run doctor to verify API access and Chrome connectivity. Report status, configuration path, and model without exposing secrets. For setup-only requests, stop after reporting the check.

Run a browser task

Before a task that may require typing, Codex must prepare candidate text and pass it through --inputs. Each candidate has a literal value and its intended purpose. Jev chooses whether to fill, which field and which candidate; code inserts that literal unchanged. Candidates are options, not mandatory steps. No text-generation model is used.

Run the entire confirmed task in one call, including the prepared candidates:

python3 <skill-dir>/scripts/jev.py run \
  --url 'https://www.bilibili.com' \
  --goal 'Search Bilibili for machine learning and open the search results.' \
  --inputs '[{"value":"machine learning","purpose":"Bilibili search query"}]' \
  --show

• Resolve only material target ambiguity before starting. Use a known starting URL; do not invent account IDs.
• Every call starts fresh. No old task, session, history or resume state is retained. Browser pages and login remain.
• Within a call, Jev receives bounded earlier page observations and navigation evidence so it can finish cross-page tasks without repeating established checks. This context is discarded on exit.
• Let Jev run until DONE or failure. Wait on the same shell process if the tool yields; do not inspect intermediate state, redelegate, supervise clicks or correct ordinary mistakes.
• Use --show only when the user asks to open, see or play the page; otherwise work in the background.
• Omit --inputs only for tasks without typing. Missing candidate text returns an input error. Never pass credentials or invent missing personal details.
• Only for an explicitly selected existing tab, use tabs to find its ID, then replace --url with --target-id ID. A new call still has fresh task context.
• When Jev returns a result, stop browser work and report that result directly. Accept DONE as the end of the task; do not independently check completion, inspect the browser again, or start a second call to verify, correct, or improve the result. Report only what the returned result supports.
• A further browser call requires a new explicit user request to continue, retry, or change the task. No separate show, finish, state or close calls after the result.
• Login, human verification, unavailable input/control, crash or the whole-call limit returns an error. Explain the blocker; user-only steps stay with the user. After their requested continuation, start a fresh call on their selected tab.

Python 3, uv and Chrome remote debugging are required. run --help lists options. Defaults are 200 actions / 300 seconds for the whole call, with no periodic handoff.