Skip to main content
Glama
Decision Browser
by HaffASE

Decision Browser is a stdio MCP server for Codex and Claude Code. Give your agent a URL, a goal and a final check. The server runs the browser task within explicit limits, checks the resulting page and returns evidence the agent can inspect.

For example: choose Zurich Airport (ZRH) from a menu that also contains the city and an airport hotel, then check the selected field value. The model chooses among observed controls; the runner rechecks the target before acting.

You supply

Decision Browser handles

You get back

Goal, URL and field values

Observation and bounded action selection

Run status, reason and recovery guidance

Functional checks

Checks against the resulting page

Verified, failed or unverified outcome

Step, time, call and byte limits

Budget enforcement and cleanup

Usage counters, timings and evidence artifacts

Experimental, version 0.1.1.

Quick start

1. Install and choose a provider

Open a terminal in your project with Node.js 20+ (including npm/npx) and your client CLI on PATH, then run the pinned npm package.

npx --yes @haffa/decision-browser@0.1.1 setup codex

Use setup claude for Claude Code or setup both for both clients. Plain setup prompts for the client. Next, select a provider and enter its API key through hidden input for a hosted preset. The preset supplies the endpoint and model. An existing local System One service is also available.

The launcher prepares uv and Python automatically. The coding client starts the MCP server. Setup downloads the pinned runtime and Chromium. For unattended installation, use install codex in place of setup codex.

Setup installs the MCP configuration, skill and sandboxed Chromium in the current project. Installation checks do not use a model key or make API requests. Add --project "/path/to/project" to choose another directory or --upgrade to update. Existing settings are preserved; conflicts stop setup. Nothing changes global client settings or grants project trust. Linux needs Playwright's host libraries and a working Chromium sandbox. Downloads require network access.

On macOS/Linux, provider selection and its key are saved outside projects in ~/.config/decision-browser/provider.json, with private file permissions. This is a local file, not encrypted storage. Windows key persistence is not supported yet; environment configuration remains available. Cancelled key entry leaves the installed runtime intact and shows a resume command.

Python, standalone archive and source-checkout alternatives · Build a reviewed installer

2. Connect your coding client

The server reads your saved profile automatically. To change providers or run an optional local diagnostic, use the same reviewed package:

npx --yes @haffa/decision-browser@0.1.1 configure
npx --yes @haffa/decision-browser@0.1.1 doctor --json

These commands reuse a cached package runtime and do not reinstall Chromium. Existing environment overrides remain supported and can take precedence over the profile; see the provider guide. Saving a key does not verify API access.

Restart the client in your project, review its trust and MCP approval prompts, confirm decision_browser connects, and load the decision-browser skill. Ask the agent to call capabilities before starting a task. The installer uses standard_form admission: review the proposed scope in the client's native form before browser work begins. Setup does not approve tools on your behalf.

3. Give the agent a task with a final check

On your own site, provide the URL, goal and exact outcome you want checked. For a small local example, serve the included counter from a development checkout:

python3.12 -m http.server 8765 --bind 127.0.0.1 --directory examples/browser-control

Then ask your agent:

Use Decision Browser in isolated mode to open http://127.0.0.1:8765/counter.html. Click inc three times and leave reset alone. Verify that #count has text 3. Allow four browser steps and four provider calls.

The opening navigation consumes one step. See the complete MCP task request. This example is optional, not an installation prerequisite; a model-driven run may incur API charges.

Installation readiness, provider access, native admission and task success are separate checks. A successful installer does not establish all four.

Related MCP server: jevnav

Try it without a model key

From the development checkout, run two synthetic tasks with a real browser and scripted decisions. They make no provider requests:

uv sync --frozen --group dev --python python3.12
.venv/bin/python -m playwright install chromium
report_dir=$(mktemp -d)
.venv/bin/python scripts/run_browser_scenarios.py \
  --cases hotel,autocomplete --output "$report_dir/scenarios.json"

These shell commands use POSIX paths and require the browser's host libraries and sandbox support. Expected summary: "status": "PASS", "passed": 2, "total": 2. The hotel task applies filters and opens Casa Flora; autocomplete selects the airport among similar labels. functional records page checks, while oracle compares expected and observed fixture events.

Use --list to see the corpus. Scripted fixture results are not live-model or native-client acceptance. Scenario guide.

How it works

A task moves from the coding agent through scope admission, a bounded observe-decide-act loop, and final checks, then returns status, usage and evidence.

The runner bounds browser steps, provider calls, input/output bytes, stored artifacts and elapsed time. Model output selects from the offered action space; it does not become arbitrary browser JavaScript. The agent supplies field values and the checks that define success.

A model saying “done” is not a verified result. Only declared functional checks can establish functional: verified. Empty checks do not verify a task, and visual diagnostics are reported separately.

MCP tools

Tool

Arguments

What it does

capabilities

None

Reports modes, actions, provider configuration and admission policy.

start_task

request

Starts one bounded task. Retain result.run_id; do not submit again to poll.

get_task

run_id?

Reads the run. {} recovers the single held run if the start reply was lost.

present_admission

run_id, proposal_id, digest

Asks the client to present the pending scope proposal.

cancel_task

run_id

Requests cancellation. Poll until cleanup finishes.

read_artifact

run_id, artifact_id; optional channel, offset, limit

Reads at most 65,536 bytes. Default legacy preserves the original small-artifact envelope; use structured or resource for paginated reads.

Keep polling queued, awaiting_human_admission and running, including a running result whose reason is finalizing. Present only the server's pending proposal and let the user respond in the client; do not fabricate an approval. Before its proposal exists, a standard-form task reports queued with reason preparing_admission. awaiting_human_admission identifies an available proposal. Domain errors retain their fixed {"error": "code"} envelope and set MCP isError: true; successful task envelopes remain result plus pending_proposal. Omitting get_task.run_id or supplying JSON null reads the current run; the literal string "null" is a run ID and never selects the current run.

The default artifact legacy channel preserves the original four fields (id, media_type, content, sha256) in both text JSON and structured output, with base64 duplication bounded to a 65,536-byte artifact. Larger artifacts or ranged legacy calls fail with artifact_range_required rather than silently truncating a purported whole artifact. For pagination, explicitly request channel: "structured" or "resource", offset (default 0), and limit (default and maximum 65,536 bytes). These range-v1 channels encode each chunk once: in structured content, or in an embedded binary resource. Both retain the artifact's full sha256 and report chunk_sha256, total_bytes, offset, next_offset and eof. Reassemble the chunks and verify the full hash. A resource URI identifies this response's bytes; it does not authorize filesystem/network access. The advertised capabilities.artifact_read describes the channel contract.

With no independent checks, DONE yields completed_unverified; UNABLE yields blocked / model_unable, also functionally unverified. With checks, their independent outcome remains decisive. Neither model stop word proves success.

One run occupies the server through retention: until the later of its original deadline plus cleanup grace or 60 seconds after execution ends. Results are held in memory, so restarting the server loses that state. Read artifacts through their advertised IDs rather than treating them as filesystem paths.

Request/result schema · Complete agent guide · Admission modes

Results and stopping conditions

Read terminal, functional, reason and recovery together:

Terminal result

Meaning

verified

Declared functional checks passed.

completed_unverified

Execution ended without verified functional success.

verification_failed

A declared outcome check failed.

blocked, refused, unsupported

Policy, admission or capability prevented completion. Inspect the reason.

limit_exceeded, cancelled, failed

A budget, cancellation or error ended the task.

outcome_unknown

An action may have happened. Reconcile the evidence before retrying.

Visual findings do not override functional results. Local geometry diagnostics cover up to three viewport sizes, but the image-inspection path reports incomplete; it is not a visual pass. See the visual task example.

Providers

Select a route with decision-browser configure, or use the advanced MCP environment settings below. Provider, model, endpoint and credential settings are not MCP task arguments.

DECISION_BROWSER_PROVIDER

Decision route

Credential

openai (default)

OpenAI Decisions

OPENAI_API_KEY

typesafe / jev

TypeSafe System One

TYPESAFE_API_KEY

openrouter

OpenRouter Decisions

OPENROUTER_API_KEY

opencode

OpenCode Console System One (Jev)

OPENCODE_API_KEY

gemini

Gemini Decision 1 through OpenCode Console

OPENCODE_API_KEY

local / nimble

Loopback System One service

No key required by default

For Gemini Decision 1, run decision-browser configure gemini and enter an OpenCode Console API key. The preset selects gemini-decision-1 automatically.

The selected route does not inherit another provider's key. Failed requests are not automatically retried or rerouted. OpenCode Go is a separate subscription; the Console route does not establish Go coverage. A local service must implement System One, not just a chat-completions endpoint.

Supply known field text through TaskRequest.values. System One decision models choose options rather than generate arbitrary text. Unbound text generation requires the separately configured text helper; OpenAI uses its native Responses helper. Helpers share the task's privacy gates, deadline and call/byte budgets.

For endpoint/model overrides, Ollama setup, choice limits, optional text helpers and credential handling, see the provider guide and Codex configuration examples.

CLI

Use the environment installed for your project. Its Python path is recorded in the generated MCP settings.

Command

Purpose

decision-browser setup [codex|claude|both]

Installs in the current project, then chooses and saves a provider interactively.

decision-browser configure [provider]

Chooses or changes the user-level provider profile.

decision-browser serve

Runs the stdio MCP server.

decision-browser doctor --json

Checks local prerequisites and configuration without an API call.

decision-browser-install --client codex --project "/path/to/project"

Runs the wheel's bundled project installer. Use claude or both as needed.

The installer entry point includes its build inputs; --source is only an optional developer override. Browser tasks are submitted through MCP, not a decision-browser run shell command.

Update or remove

Repeating an install prepares and probes a fresh runtime before switching managed registrations. To use a reviewed new distribution, add --upgrade and include every previously installed client:

python3.12 /path/to/decision-browser.pyz --client both --project "/path/to/project" --upgrade
python3.12 /path/to/decision-browser.pyz --client both --project "/path/to/project" --uninstall

Removal deletes unchanged managed entries and skills, preserving other settings. Runtime/cache files remain for manual cleanup. Edited managed files stop the operation instead of being overwritten. Close clients before changing their registrations. Conflicts and recovery.

Boundaries

Area

Current behavior

Actions

Navigation, click, fill, native select, Enter, submit, scroll, wait and screenshot.

Unsupported interactions

Frames, shadow DOM, canvas interaction, file transfers and opening additional tabs are outside the action set.

isolated session

Creates a fresh browser context. Prefer this for initial evaluation.

existing_chrome session

Uses one owned tab in a selected existing context and shares its cookies. Treat this as access to the logged-in account.

Consequential effects

Recognized purchase, send, publish, delete, transfer and booking actions are blocked. Ordinary controls can still autosave or cause other site effects.

Privacy

Page-derived data and supplied values may reach the configured provider. Image settings do not stop text transmission; redaction is not universal.

Installation

Local project setup for Codex and Claude Code. Cloud/Cowork installation is not provided; native Windows installation has not been exercised.

Admission is not an OS or network sandbox, and page content is untrusted. Use authorized sites and minimally privileged accounts. Chromium's sandbox stays enabled; do not disable it to work around launch failures. Inspect screenshots and artifacts before sharing them.

Native human admission and live provider access need separate verification in each actual client. Local fixtures and mocked transport tests do not establish that compatibility or production readiness.

Security policy · Action classification

Benchmarks

Browser tests: 17 November 2026

The baseline snapshot ran all 21 published cases three times on each route: 189 real browser attempts, including every failed attempt. Twenty cases use synthetic fixtures; public_about follows Python.org's public About link.

Agent and route

Confirmed

Physical API calls

Reported input tokens

Reported output tokens

Decision Browser · TypeSafe Jev jev-1.14.0

13/63

530

1,810,309

161,088

Decision Browser · OpenAI Decisions gpt-6-luna

52/63

293

738,574 + unknown

0 + unknown

Standalone Terra · gpt-6.1-terra, medium

57/63

384

390,682

9,744

One Decisions call returned HTTP 503 and its usage was not captured. Its token consumption is unknown and excluded from the reported partial totals. No attempt was retried. Jev used TypeSafe directly, with jev-latest resolving to jev-1.14.0. Confirmation requires native completion, independent page and event checks, cleanup, and complete reported input/output usage. All sessions were isolated; Core used development task_scope admission.

All case results, errors, token details and source snapshots · 189 audited attempts (CSV) · Audit and reporting correction.

Failure rerun

The updated snapshot reran each of the 67 unconfirmed attempts once with the same goals and limits. The last column combines the retained baseline successes with confirmations from the rerun.

Agent and route

Baseline confirmed

Confirmed in rerun

Retained + recovered

Decision Browser · TypeSafe Jev jev-1.14.0

13/63

9/50

22/63

Decision Browser · OpenAI Decisions gpt-6-luna

52/63

7/11

59/63

Standalone Terra · gpt-6.1-terra, medium

57/63

6/6

63/63

Per-case results, timings, token usage and remaining errors · Rerun attempt CSV.

OpenCode Console

Two fresh series ran all 21 cases with three repetitions per model on the paid Console System One API. The direct TypeSafe series above used Jev 1.14.0, while Console used Jev 1.13.

Model

Confirmed

Median attempt

Input tokens

Output tokens

Jev 1.13

58/63

4.12 s

1,370,208

110,282

Gemini Decision 1

63/63

5.04 s

1,217,843

0

Console results by case, token usage and failures · All 126 attempts (CSV).

Archived measurements

The static charts below keep every model visible at once. Longer workflows and short tasks have separate figures and cost denominators. Completion comes first; a fast early stop is not a successful task.

These measurements predate this release candidate. They use the former name Decision Browser Core and retain their original revisions, models, failures, budgets and scoring rules. Their source commits are not part of the new clean-history repository. These are newly drawn charts of archived data, not new measurements of this tree.

Long workflows: 5 tasks, 3 repetitions

Historical long workflows: confirmed attempts out of 15, median process time and estimated cost for all seven agent/model configurations.

Method, per-task outcomes and source revisions. Core's 30 attempts were rerun; the other 75 are from the earlier series. The series ran at different times. The chart uses the latest recorded Core results.

Short tasks: 16 tasks, 3 repetitions

Historical short tasks: confirmed attempts out of 48, median process time and estimated cost for all seven agent/model configurations.

Source report

What it covers

GPT-6 Luna libraries

Library comparison and the context-cost follow-up.

Standalone Terra

The separate Terra comparison and its scoring.

Core with Jev

Decision Browser Core provider outcomes, timings and estimated costs.

Other Jev libraries

The jev-ra and jev-ultrafast provider comparison.

Each configuration's median includes unsuccessful attempts and early stops. Time includes process/browser startup and cleanup. Costs are estimates for scored calls, not full experiment spending. The short-suite configurations come from separate benchmark series. No result here guarantees general-site reliability. The original animated comparison remains available as a historical artifact; the README does not autoplay it.

FAQ

Do I need a model key to install it? The unattended install command needs none. Interactive setup installs first, then asks for the chosen hosted provider's key. Neither makes a provider request. Real model-driven tasks need a configured provider; the scripted fixtures above do not.

Can I use my signed-in Chrome? existing_chrome is available under the standard-form policy. It shares the selected context's cookies, so use a dedicated test account and review the requested scope. See admission modes.

Does doctor prove that my provider works? No. It checks local prerequisites and configuration without contacting the API. Entitlement, native approval and a verified browser task each require their own acceptance check.

What if the task stops after a click? Inspect the result and evidence. In particular, outcome_unknown means the action may have happened; do not blindly resubmit the task.

Development

Use Python 3.11+, uv, Node.js and the pinned full Chromium with its host libraries. CI covers Python 3.11–3.13. From the checkout, with prerequisites available, run:

python3.12 -I scripts/verify.py --profile full --output-dir ../verification-new

Choose a fresh output directory outside the repository. The verifier builds and installs the exact wheel, checks dependencies, lint and types, then runs unit and owned-browser tests. It makes no paid model requests. An offline unit pass is not a full browser-suite pass.

Contributing · Verification guide · Native client acceptance · Live acceptance

Decision Browser is MIT licensed. Distributed upstream excerpts retain their third-party notices. README layout inspiration: jev-ra; its prose and artwork are not reproduced here.

Installation · Support · Changelog · Release checklist · Release procedure

The remaining work toward the one-command public release is tracked in the delivery plan.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Provides browser automation tools for coding agents—goto, browse, goal, page_state, and summary—so agents can drive real pages through auditable, gated decisions and record traces for offline replay.
      33
      65 PyPI
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients such as Claude Desktop, Claude Code and IDE agents to call a tool that drives a real Playwright browser to complete web tasks, with sensitive actions automatically refused when no human is available to approve them.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables Claude Code to control Google Chrome using local Playwright sessions to navigate, click, fill forms, take screenshots, and read pages, with security guards and an audit log.
      6
      MIT