CUAWright

Most web agents today treat the browser session itself as the workspace: at each step the model receives the current page state and predicts a single next operation — a click, a type, a DOM selector, or a short tool call. Whatever the format, the agent is locked into predicting one web action at a time inside a predefined interaction loop. That harness was useful when LLMs were weaker. As models get stronger at writing and debugging code, the same harness becomes a bottleneck.

Webwright takes a different stance: separate the agent from the browser, and treat the browser as something the agent can launch, inspect, and discard while developing a program. The persistent artifact is not the browser session — it's the code and logs in the local workspace.

• 🧱 Robust, reusable interaction with web environments — instead of fragile pixel-level actions, a coding agent with a terminal queries elements, waits for conditions, and handles dynamic behaviors like lazy loading or re-rendering. The resulting scripts can be rerun, adapted, and shared across tasks rather than rediscovered from scratch.
• ⚡ Efficient composition of complex workflows — multi-step interactions like selecting a date or filling a form become a compact program. Loops, functions, and abstractions let the agent generalize across similar tasks (e.g. different dates) without re-predicting the same low-level sequences. Fewer interaction rounds, faster execution, less error accumulation on long horizons.
• 🧪 Workspace-as-state, not browser-as-state — the agent can write exploratory scripts, spawn fresh browser sessions, and decide for itself when to capture screenshots and inspect failures, much like a human engineer iterating on an RPA script.
• 🪄 Surprisingly effective despite being minimal — this stripped-down setup turns out to handle complex and especially long-horizon web tasks well (see Performance).

Most web agent frameworks bury the actual agent loop under layers of abstractions. Webwright takes the opposite stance:

• 🪶 Readable core — browser agent loop, environments, models, and CLI are separate modules under src/cuawright/webwright/.
• 🧩 Pluggable model backends — OpenAI, Anthropic, and OpenRouter, each ~150–200 lines.
• 🔍 Zero hidden frameworks — just httpx, pydantic, playwright, and typer.
• 🔁 Flat prompt → observe → execute script loop — readable end-to-end, easy to debug, easy to fork.
• 🧪 Run-artifact first — every run writes trajectories and screenshots to disk for inspection.

If you want a minimal, easy-to-debug starting point for browser-using agents instead of another heavyweight platform, this is it.

How they differ at the architectural level:

Install through the bundled marketplace inside Claude Code:

# 1. Add this repo as a Claude Code plugin marketplace
/plugin marketplace add microsoft/Webwright

# 2. Install the plugin from that marketplace
/plugin install cuawright@cuawright

Prefer a local checkout? Point the marketplace command at the cloned repo instead:

/plugin marketplace add /absolute/path/to/Webwright
/plugin install cuawright@cuawright

Start a new Claude Code session after installing — plugins are loaded at session start and won't appear until you restart.

You can either ask Claude Code in plain English (the skill auto-activates from its description), or use one of the slash commands:

/cuawright:run search Google Flights for flights from SEA to JFK on 2026-08-15 to 2026-08-20
/cuawright:craft search a ticket on Google Flights from LAX to SFO depart June 7 return June 14

• /cuawright:run (or any plain prompt) produces a one-shot final_script.py for the literal task values.
• /cuawright:craft produces a reusable CLI tool: final_script.py becomes one parameterized function with a Google-style Args: docstring and an argparse wrapper whose flags default to the concrete task values, so you can rerun it later with different arguments — e.g. python final_script.py --origin JFK --destination LAX --depart-date 2026-07-01.

In both modes Claude Code scaffolds a workspace with plan.md, runs instrumented Playwright scripts under final_runs/run_<id>/, and visually self-verifies each critical point against the saved screenshots.

Codex reads Claude-style marketplaces, so the same repo works as a Codex plugin marketplace. From the Codex CLI:

# 1. Add this repo as a Codex plugin marketplace
codex plugin marketplace add microsoft/Webwright

# 2. Open the plugin browser and install CUAWright
codex
/plugins

Prefer a local checkout?

codex plugin marketplace add /absolute/path/to/Webwright

Then restart Codex so the new marketplace and plugin are picked up.

In a new Codex thread, either ask in plain English (the skill auto-activates from its description) or invoke the bundled skill explicitly with @cuawright-web:

@cuawright-web search Google Flights for flights from SEA to JFK on 2026-08-15 to 2026-08-20

Codex scaffolds a workspace with plan.md, runs instrumented Playwright scripts under final_runs/run_<id>/, and visually self-verifies each critical point against the saved screenshots.

To turn the plugin off without uninstalling, set its entry in ~/.codex/config.toml to enabled = false and restart Codex.

Hermes Agent is a skills-compatible client, so the same skills/cuawright-web/ folder loads as a Hermes skill. Symlink it into your Hermes user-skills directory:

mkdir -p ~/.hermes/skills
ln -sfn /absolute/path/to/Webwright/skills/cuawright-web ~/.hermes/skills/cuawright-web

No Hermes-specific manifest is needed; only SKILL.md is loaded.

Start Hermes (hermes) and ask it to drive a web task in natural language — the skill auto-activates from its description. You can also invoke it explicitly with /cuawright-web.

Note: the named subcommands shipped under skills/cuawright-web/commands/ (/cuawright:run, /cuawright:craft) are a Claude Code / Codex convention and are inert in Hermes; the skill itself still works end-to-end.

A tiny Flask app under assets/task_showcase/ consolidates Webwright runs for repeatable odyssey tasks (deals, inventory, listings, job boards, weather, etc.) into a single dashboard. Each task ships only two files — task.json (metadata) and report.json (curated, structured output: sources + result sections like tables, lists, summaries) — and the templates render them generically, so adding a new task is just dropping a new folder in assets/task_showcase/tasks/.

pip install flask
python assets/task_showcase/app.py    # http://127.0.0.1:5005

To have Webwright produce a renderer-ready task folder at runtime, stack the Task Showcase overlay:

python -m cuawright.webwright.run.cli main \
    -c base.yaml -c model_openai.yaml -c task_showcase.yaml \
    -t "<repeatable web task>" \
    --task-id my_repeatable_task \
    -o outputs/default

Note: report.json is only generated when -c task_showcase.yaml is included. A plain base.yaml run produces trajectory.json and debug artifacts but no report.json.

The run writes task_showcase/tasks/<short_id>/task.json and report.json inside the output workspace. Render those generated files without copying them back into the repo:

python assets/task_showcase/app.py \
    --tasks-dir outputs/default/<run>/task_showcase/tasks

Skill Factory is an optional extension for learning and reusing browser automation scripts. Install it from this checkout:

pip install -e ".[skill-factory]" -e extensions/skill-factory
cuawright-skill-factory --help

For desktop execution and Skill Factory together, use pip install -e ".[desktop,skill-factory]" -e extensions/skill-factory.

Most agent skills are context the model reads. Ours are programs. cuawright.webwright.skill_factory distills the script every solve leaves behind into a growing library of reusable, verified, parameterized skills — code you can run without a model and compose into the next task instead of re-exploring the site. Plugs in with no change to the agent loop:

• Reuse — before a solve starts, the library is checked out of the agent loop (recommend): route either runs a matching skill directly (no model) or injects it into the prompt as a prior ({verdict: run|adapt|skip, skill_id, source_path}); the agent reuses the hint without ever querying the library itself.
• Grow — afterwards, python -m cuawright.webwright.skill_factory learn outputs/ --library ./library groups solves of the same template and distills one parameterized skill (build does solve→learn in one shot; update is manual-manifest mode).

Before adding a skill, the input gate compares the result with gold answers when available. Otherwise it checks the output's shape and the agent's reported success; this fallback can admit an incorrect answer. The generated script is then replayed without a model, and updates are checked against previous examples.

Once learned, a skill runs standalone in ~40 s with zero tokens. On WebArena (10 retrieve-type templates, 3 self-hosted sites, gpt-5.4) reuse lifts held-out accuracy 55% → 70% (+15 pp) while cutting steps. See extensions/skill-factory/src/cuawright/webwright/skill_factory/README.md.

You can run the same tasks using the Webwright harness and its Codex / GitHub Copilot skill variant, and see how token usage and trajectories stack up between different harnesses. The trajectory viewer supports Codex, GitHub Copilot and Webwright harness traces.

cd assets/compare_trajectory/
python3 -m http.server

Open the webpage in your browser and upload the Webwright raw_responses.jsonl and attach trajectory.json to view. Then on the other side you can upload your Codex or GitHub Copilot trace.

ls ~/.codex/sessions/2026/MONTH/DAY/SESSION_ID.jsonl

/export file session
-> session.md is the uploadable trace

The Codex cached-token count is omitted because the recorded figure needs verification. Individual runs and results may vary.