# microsoft/webwright architecture

> Architecture diagram of the GitHub repository microsoft/webwright, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/webwright
- Repository: https://github.com/microsoft/webwright

## Overview

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.

Main entry points: [`src/webwright/agents/default.py`](https://github.com/microsoft/webwright/blob/main/src/webwright/agents/default.py) (Agent loop), [`src/webwright/config/base.yaml`](https://github.com/microsoft/webwright/blob/main/src/webwright/config/base.yaml) (Config core), [`src/webwright/run/cli.py`](https://github.com/microsoft/webwright/blob/main/src/webwright/run/cli.py) (CLI), [`src/webwright/models/base.py`](https://github.com/microsoft/webwright/blob/main/src/webwright/models/base.py) (Model API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_doctor["Doctor<br/>healthcheck<br/>[doctor.py]"]
end

subgraph group_env["Environment"]
  node_workspace[("Workspace<br/>filesystem state<br/>[local_workspace.py]")]
  node_browser["Browser<br/>playwright env<br/>[local_browser.py]"]
  node_artifacts[("Run artifacts<br/>output bundle<br/>[report.json]")]
end

subgraph group_models["Models"]
  node_model_api["Model API<br/>provider interface<br/>[base.py]"]
  node_openai["OpenAI<br/>provider adapter<br/>[openai_model.py]"]
  node_anthropic["Anthropic<br/>provider adapter<br/>[anthropic_model.py]"]
  node_openrouter["OpenRouter<br/>provider adapter"]
end

subgraph group_tools["Tools"]
  node_image_qa["Image QA<br/>vision helper<br/>[image_qa.py]"]
  node_reflection["Reflection<br/>repair helper<br/>[self_reflection.py]"]
  node_browser_persist["Persist browser<br/>browser helper"]
  node_model_config["Model config<br/>routing helper<br/>[_model_config.py]"]
end

subgraph group_showcase["Showcase"]
  node_showcase_app["Task showcase<br/>flask app<br/>[app.py]"]
  node_showcase_templates["Templates<br/>[dashboard.html]"]
  node_trajectory_viewer["Trajectory viewer<br/>static viewer<br/>[app.js]"]
end

subgraph group_integrations["Integrations"]
  node_plugin_manifest["Plugin manifests<br/>integration<br/>[plugin.json]"]
  node_skill_pack["Skill pack<br/>integration<br/>[SKILL.md]"]
end

node_agent_loop(("Agent loop<br/>orchestrator<br/>[default.py]"))
node_config_core["Config core<br/>configuration<br/>[base.yaml]"]

node_cli -->|"loads"| node_config_core
node_cli -->|"checks"| node_doctor
node_cli -->|"creates"| node_workspace
node_cli -->|"starts"| node_agent_loop
node_agent_loop -->|"queries"| node_model_api
node_agent_loop -->|"writes"| node_workspace
node_agent_loop -->|"drives"| node_browser
node_agent_loop -->|"uses"| node_image_qa
node_agent_loop -->|"uses"| node_reflection
node_agent_loop -->|"routes"| node_model_config
node_model_api -->|"implements"| node_openai
node_model_api -->|"implements"| node_anthropic
node_model_api -->|"implements"| node_openrouter
node_browser_persist -->|"configures"| node_browser
node_showcase_app -->|"renders"| node_showcase_templates
node_showcase_app -->|"reads"| node_artifacts
node_trajectory_viewer -->|"reads"| node_artifacts
node_plugin_manifest -->|"exposes"| node_skill_pack
node_skill_pack -->|"invokes"| node_cli
node_config_core -->|"enables"| node_browser_persist
node_config_core -->|"enables"| node_showcase_app
node_config_core -->|"selects"| node_openai
node_config_core -->|"selects"| node_anthropic
node_config_core -->|"selects"| node_openrouter

click node_cli "https://github.com/microsoft/webwright/blob/main/src/webwright/run/cli.py"
click node_doctor "https://github.com/microsoft/webwright/blob/main/src/webwright/run/doctor.py"
click node_agent_loop "https://github.com/microsoft/webwright/blob/main/src/webwright/agents/default.py"
click node_workspace "https://github.com/microsoft/webwright/blob/main/src/webwright/environments/local_workspace.py"
click node_browser "https://github.com/microsoft/webwright/blob/main/src/webwright/environments/local_browser.py"
click node_model_api "https://github.com/microsoft/webwright/blob/main/src/webwright/models/base.py"
click node_openai "https://github.com/microsoft/webwright/blob/main/src/webwright/models/openai_model.py"
click node_anthropic "https://github.com/microsoft/webwright/blob/main/src/webwright/models/anthropic_model.py"
click node_openrouter "https://github.com/microsoft/webwright/blob/main/src/webwright/models/openrouter_model.py"
click node_image_qa "https://github.com/microsoft/webwright/blob/main/src/webwright/tools/image_qa.py"
click node_reflection "https://github.com/microsoft/webwright/blob/main/src/webwright/tools/self_reflection.py"
click node_browser_persist "https://github.com/microsoft/webwright/blob/main/src/webwright/tools/persistent_local_browser.py"
click node_model_config "https://github.com/microsoft/webwright/blob/main/src/webwright/tools/_model_config.py"
click node_showcase_app "https://github.com/microsoft/webwright/blob/main/assets/task_showcase/app.py"
click node_showcase_templates "https://github.com/microsoft/webwright/blob/main/assets/task_showcase/templates/dashboard.html"
click node_trajectory_viewer "https://github.com/microsoft/webwright/blob/main/assets/compare_trajectory/app.js"
click node_plugin_manifest "https://github.com/microsoft/webwright/blob/main/.claude-plugin/plugin.json"
click node_skill_pack "https://github.com/microsoft/webwright/blob/main/skills/webwright/SKILL.md"
click node_config_core "https://github.com/microsoft/webwright/blob/main/src/webwright/config/base.yaml"
click node_artifacts "https://github.com/microsoft/webwright/blob/main/assets/task_showcase/tasks/austin_apartments/report.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_doctor toneBlue
class node_workspace,node_browser,node_artifacts toneAmber
class node_model_api,node_openai,node_anthropic,node_openrouter toneMint
class node_image_qa,node_reflection,node_browser_persist,node_model_config toneRose
class node_showcase_app,node_showcase_templates,node_trajectory_viewer toneIndigo
class node_plugin_manifest,node_skill_pack toneTeal
class node_agent_loop,node_config_core toneNeutral
```

## Components

### Runtime

CLI entrypoint, orchestration, and health checks

- [CLI](https://github.com/microsoft/webwright/blob/main/src/webwright/run/cli.py): entrypoint · webwright command entrypoint that loads config and starts runs · `src/webwright/run/cli.py`
- [Doctor](https://github.com/microsoft/webwright/blob/main/src/webwright/run/doctor.py): healthcheck · Checks local prerequisites and runtime readiness · `src/webwright/run/doctor.py`

### Environment

Persistent workspace and disposable browser boundary

- [Workspace](https://github.com/microsoft/webwright/blob/main/src/webwright/environments/local_workspace.py): filesystem state · Durable run state and artifacts stored on disk · `src/webwright/environments/local_workspace.py`
- [Browser](https://github.com/microsoft/webwright/blob/main/src/webwright/environments/local_browser.py): playwright env · Local Playwright/Chromium session management · `src/webwright/environments/local_browser.py`
- [Run artifacts](https://github.com/microsoft/webwright/blob/main/assets/task_showcase/tasks/austin_apartments/report.json): output bundle · Trajectory, screenshots, reports, and other persisted run outputs · `assets/task_showcase/tasks/austin_apartments/report.json`

### Models

Shared model interface and provider adapters

- [Model API](https://github.com/microsoft/webwright/blob/main/src/webwright/models/base.py): provider interface · Common backend contract used by the agent loop · `src/webwright/models/base.py`
- [OpenAI](https://github.com/microsoft/webwright/blob/main/src/webwright/models/openai_model.py): provider adapter · OpenAI-specific request and response handling · `src/webwright/models/openai_model.py`
- [Anthropic](https://github.com/microsoft/webwright/blob/main/src/webwright/models/anthropic_model.py): provider adapter · Anthropic-specific request and response handling · `src/webwright/models/anthropic_model.py`
- [OpenRouter](https://github.com/microsoft/webwright/blob/main/src/webwright/models/openrouter_model.py): provider adapter · OpenRouter-specific request and response handling · `src/webwright/models/openrouter_model.py`

### Tools

Run-time helpers and model-dependent utilities

- [Image QA](https://github.com/microsoft/webwright/blob/main/src/webwright/tools/image_qa.py): vision helper · Screenshot analysis helper for models that need image interpretation · `src/webwright/tools/image_qa.py`
- [Reflection](https://github.com/microsoft/webwright/blob/main/src/webwright/tools/self_reflection.py): repair helper · Self-debugging and repair loop helper · `src/webwright/tools/self_reflection.py`
- [Persist browser](https://github.com/microsoft/webwright/blob/main/src/webwright/tools/persistent_local_browser.py): browser helper · Behavior for keeping browser sessions alive across runs · `src/webwright/tools/persistent_local_browser.py`
- [Model config](https://github.com/microsoft/webwright/blob/main/src/webwright/tools/_model_config.py): routing helper · Routes tool usage to the configured model backend · `src/webwright/tools/_model_config.py`

### Showcase

Reporting and task presentation surfaces

- [Task showcase](https://github.com/microsoft/webwright/blob/main/assets/task_showcase/app.py): flask app · Presentation layer for completed tasks and reports · `assets/task_showcase/app.py`
- [Templates](https://github.com/microsoft/webwright/blob/main/assets/task_showcase/templates/dashboard.html): ui templates · Dashboard and task HTML templates for showcase rendering · `assets/task_showcase/templates/dashboard.html`
- [Trajectory viewer](https://github.com/microsoft/webwright/blob/main/assets/compare_trajectory/app.js): static viewer · Client-side comparison viewer for saved trajectories and responses · `assets/compare_trajectory/app.js`

### Integrations

External host/plugin entry points

- [Plugin manifests](https://github.com/microsoft/webwright/blob/main/.claude-plugin/plugin.json): integration · Claude and Codex plugin entry manifests · `.claude-plugin/plugin.json`
- [Skill pack](https://github.com/microsoft/webwright/blob/main/skills/webwright/SKILL.md): integration · Shared skill, commands, and reference docs for external hosts · `skills/webwright/SKILL.md`

### Other components

- [Agent loop](https://github.com/microsoft/webwright/blob/main/src/webwright/agents/default.py): orchestrator · Main task loop that coordinates model calls, actions, results, and iteration · `src/webwright/agents/default.py`
- [Config core](https://github.com/microsoft/webwright/blob/main/src/webwright/config/base.yaml): configuration · Base and overlay YAML configuration for runtime, model, and environment modes · `src/webwright/config/base.yaml`

## Connections

- CLI → Config core: loads · CLI assembles layered runtime configuration
- CLI → Doctor: checks · Runs prerequisite verification before execution
- CLI → Workspace: creates · Initializes the run workspace and output location
- CLI → Agent loop: starts · Hands control to the main agent orchestration loop
- Agent loop → Model API: queries · Sends task context and receives model outputs
- Agent loop → Workspace: writes · Persists state, artifacts, and run traces
- Agent loop → Browser: drives · Executes browser actions through Playwright
- Agent loop → Image QA: uses · Analyzes screenshots when visual inspection is needed
- Agent loop → Reflection: uses · Invokes repair and self-debugging support
- Agent loop → Model config: routes · Selects the configured helper or provider path
- Model API → OpenAI: implements · OpenAI provider adapter
- Model API → Anthropic: implements · Anthropic provider adapter
- Model API → OpenRouter: implements · OpenRouter provider adapter
- Persist browser → Browser: configures · Adjusts browser lifecycle behavior for persistent mode
- Task showcase → Templates: renders · Flask app serves dashboard and task views
- Task showcase → Run artifacts: reads · Consumes generated task and report artifacts
- Trajectory viewer → Run artifacts: reads · Loads saved trajectory and raw response files
- Plugin manifests → Skill pack: exposes · Plugin entry points surface the shared skill package
- Skill pack → CLI: invokes · External hosts can call the webwright runtime command
- Config core → Persist browser: enables · Overlay selects persistent browser mode
- Config core → Task showcase: enables · Overlay selects task showcase mode
- Config core → OpenAI: selects · Overlay selects the OpenAI backend
- Config core → Anthropic: selects · Overlay selects the Anthropic backend
- Config core → OpenRouter: selects · Overlay selects the OpenRouter backend