microsoft/webwright

1. What this repository is

Webwright is a minimal browser-agent runtime built around a terminal, a local workspace, and a Playwright-driven Chromium browser. The core idea is that the agent’s durable state lives in files on disk, not in a long-lived browser session.

2. Primary execution entrypoint

The main runtime path starts in src/webwright/run/cli.py, which exposes the webwright command. It loads layered YAML config, validates runtime prerequisites, creates the run workspace, and hands control to the agent loop.

3. Core agent loop

src/webwright/agents/default.py is the central orchestration layer. It repeatedly:

- sends task/context to the selected model backend,

- receives code or actions,

- executes them in the environment,

- captures results, screenshots, and traces,

- and iterates until the task is done.

This is intentionally flat and script-oriented rather than a multi-agent or graph-based system.

4. Environment boundary: local workspace + browser

The environment layer in src/webwright/environments/ splits into two concerns:

- local_workspace.py for filesystem-backed run state and artifacts,

- local_browser.py for launching and managing Playwright/Chromium sessions.

The browser is treated as disposable; the workspace is the persistent record of the run.

5. Model backend abstraction

src/webwright/models/ provides a backend interface plus provider-specific adapters for OpenAI, Anthropic, and OpenRouter. This is the main external API boundary in the system. The agent loop talks to a common model interface, while provider modules handle auth, request shaping, and response parsing.

6. Tooling and model-dependent helpers

src/webwright/tools/ contains auxiliary capabilities used during runs, especially:

- image_qa.py for analyzing screenshots,

- self_reflection.py for debugging/repair loops,

- persistent_local_browser.py for browser persistence behavior,

- _model_config.py for routing tool usage to the configured model.

These tools are there to compensate when the primary model cannot directly inspect images or needs additional introspection.

7. Configuration model

Config is layered from src/webwright/config/, with base.yaml as the common core and separate overlays for model choice and environment mode, such as model_openai.yaml, model_claude.yaml, local_browser.yaml, persistent_browser.yaml, and task_showcase.yaml. This lets the same agent logic run in different deployment modes without changing code.

8. Artifacts and run outputs

Each run writes structured artifacts to the output workspace, including trajectories, screenshots, and other debugging files. The README also describes task_showcase/tasks/<id>/task.json and report.json when the showcase overlay is enabled. These artifacts are central to debugging, replaying, and comparing runs.

9. Task Showcase subsystem

assets/task_showcase/ is a separate Flask-based presentation layer for repeatable tasks. It renders generated task.json and report.json files into a dashboard using templates/dashboard.html and templates/task.html. This is not part of the agent loop itself; it is a reporting/viewing boundary for completed runs.

10. Trajectory comparison and trace viewing

assets/compare_trajectory/ is a static client-side viewer for comparing traces from Webwright and other agent harnesses. It consumes saved run data such as trajectory.json and raw_responses.jsonl, making trajectory inspection a first-class post-run workflow.

11. Plugin/skill integration boundary

The repo also ships integration surfaces for external agent hosts:

- .claude-plugin/ and .codex-plugin/ provide marketplace/plugin manifests,

- skills/webwright/ contains the shared skill, commands, and reference docs.

In these modes, Webwright can be invoked from Claude Code, Codex, OpenClaw, or Hermes, but the same underlying browser-task workflow and workspace artifact model still applies.

12. Supporting infrastructure

src/webwright/utils/ holds cross-cutting support such as logging, runtime helpers, and serialization. src/webwright/run/doctor.py is the health-check path for verifying local prerequisites. Tests currently focus on doctor behavior and tool-routing correctness, indicating the repo’s main failure points are environment readiness and model/tool dispatch.