Browser Automation on KnightLi Blog

How browser-harness domain skills keep AI agents from repeating browser automation mistakes

Sun, 24 May 2026 23:43:35 +0800

The most interesting part of browser-use/browser-harness is not only that it lets AI agents control real Chrome. It also turns web-operation experience into reusable domain skills.

That matters because browser automation is rarely difficult only because of clicking buttons. Each website has its own details:

Which pages require login.
Which data can be fetched directly through an API.
Which buttons do not respond to normal DOM clicks.
Which iframes, shadow DOM components, or popups block the flow.
Which selectors are stable and which are temporary classes.
Which actions involve accounts, payments, or irreversible changes and require human confirmation.

If this experience only stays in one task log, the agent will hit the same problems again next time. domain skills are meant to preserve that experience so the agent does not start from zero every time it opens a site.

What domain skills are

You can think of domain skills as site-operation manuals for agents.

They are not ordinary user documentation, and they are not one-off scripts. They are closer to field-tested site knowledge:

Whether the site is suitable for browser automation.
Which API should be used first if an API exists.
Which URL should be used when the browser is necessary.
Which DOM structures, aria-labels, and button behaviors have been verified.
Which common approaches fail.
Which scenarios should stop and ask for human intervention.

This content can be reviewed by humans and read by agents during tasks. It turns on-the-spot exploration into maintainable experience.

A good browser agent should not turn every problem into opening a webpage, looking at screenshots, and clicking buttons.

One important kind of experience in domain skills tells the agent when not to use the browser.

For sites such as ArXiv, paper search, metadata, and abstracts can be fetched directly through the Atom API or HTML meta tags. HTTP requests are usually faster, more stable, and easier to parse than opening a browser.

GitHub follows a similar pattern. Repository, user, and release data should use the REST API first. File contents should use raw.githubusercontent.com first. Only pages such as GitHub Trending, which do not have an equivalent API, need browser interaction.

This shows that browser-harness is not based on “the browser solves everything.” It puts the browser in the right place: when APIs, HTTP, and static pages cannot solve the problem, let the agent operate a real page.

They store site-level knowledge

Traditional automation scripts are usually written around one task, for example:

`1`	`Open page -> enter keyword -> click button -> download file`

That script may complete the task, but the experience is scattered inside code. When the site changes, the script may fail. When the task changes, much of the experience may not be reusable.

domain skills are closer to a site-level knowledge base. They care about:

Which container selector is stable in Amazon search results.
Which GitHub data should go through the REST API.
How LinkedIn invitation buttons differ in aria-label.
Which Shopify Admin pages are embedded apps.
Why Shopify Polaris inputs cannot always be filled with normal JS value assignment.
How Browser Use Cloud browser instances are created, listed, and cleaned up.

These are not steps for one task. They are decision-making knowledge that many future tasks can reuse.

Example: Amazon product search

For Amazon product search, the important part is not only how to search, but which path is more stable.

A more reliable approach is to use a direct search URL instead of opening the homepage and simulating typing every time. Search results can be extracted from a container such as [data-component-type="s-search-result"]. Field extraction also has details: title, price, rating, review count, and sponsored status each have more stable DOM sources.

This kind of experience is valuable for an agent. Without it, the agent may guess buttons from screenshots and repeatedly try selectors. With it, the agent can go directly to a more stable extraction path.

More importantly, a skill can record traps. For example, some selectors that look usable may misread sponsored results or cross-sell areas. You only learn that from field testing.

Example: LinkedIn invitation management

LinkedIn is closer to a real account workflow, and the risk is higher.

On the invitation manager page, the Accept and Ignore buttons use different aria-label formats. You cannot simply derive one from the other. Some invitation cards even render Accept as an <a> element rather than a <button>, and ordinary CDP clicks may not trigger the accept action.

This shows that real web automation does not end when an element is located. Button labels, event binding, soft navigation, and component implementation all affect whether an action really works.

For an agent, this experience also has a safety meaning. Operations involving social accounts, invitations, messages, and posting should not be fully delegated. A skill can record the path and traps, but accepting invitations in bulk, sending content externally, or changing account details should keep human confirmation.

Example: Shopify Admin

Shopify Admin shows another issue: backend systems are often not one page, but a combination of embedded apps and complex components.

Many Shopify apps run inside iframes. Polaris React inputs, Web Components, and embedded apps all behave differently. Some inputs cannot be filled with element.value = ...; they need CDP keystrokes that are closer to real keyboard input.

The value of this kind of skill is that it lets the agent first identify what kind of UI it is looking at, then choose the right operation method.

Shopify experience also emphasizes “do not use the browser if you do not have to”:

For read-only product and inventory data, use the Storefront API first.
If an Admin API token exists, use the Admin API first.
For theme code editing, use Shopify CLI first.
Use the browser only when there is no API, the change is rare, or you are exploring the admin.

That is a mature tool-selection logic for agents.

Example: Browser Use Cloud

domain skills do not only serve webpage clicking. They can also record API experience around browser runtimes.

Browser Use Cloud experience can record how to create cloud browsers through REST APIs, list running browsers, clean up zombie browsers, and obtain liveUrl and cdpUrl.

This means a skill is not limited to “how to click a button.” Any recurring task with a stable method can become a skill:

API call patterns.
Authentication header format.
Request and response structure.
Verified status codes.
Common failure modes.
Resource cleanup and recycling methods.

For agents, all of these are reusable capabilities.

Why this is more reliable than ad-hoc reasoning

Many people expect a large model to understand the webpage by itself every time. In real tasks, relying only on ad-hoc reasoning is unstable.

The reasons are simple:

Web UI changes often.
The same button may have multiple implementations.
Visible does not mean clickable.
Clickable does not mean the action really worked.
Some tasks should use APIs instead of browsers.
Some operations require human confirmation and should not be decided by the model alone.

Writing these experiences into files brings several benefits:

Humans can review them.
Wrong experience can be corrected.
Site knowledge can accumulate over time.
New agents can inherit old experience.
Temporary task discoveries can become long-term knowledge.

This is more stable than putting everything into a prompt or chat context.

How teams can use it

In a team, domain skills can become a lightweight automation knowledge base.

Useful content to record includes:

Post-login paths in internal systems.
Report export flows.
Common popup handling.
Which buttons require human confirmation.
Which pages have API alternatives.
Which selectors were tested and found reliable.
Which tasks agents are not allowed to run automatically.

This knowledge does not need to be complete at the beginning. A practical path is to start with low-risk, frequent, reversible workflows: read-only tasks, downloads, organization, and checks. Once the flow is stable, turn the experience into a skill.

For team managers, skill files also make automation boundaries visible. You can inspect what the agent knows, what it can do, and where it should stop.

Boundaries to keep

domain skills can improve an agent’s success rate, but they should not fully automate high-risk operations.

Several boundaries matter:

Do not record passwords, Cookie, token, customer data, or sensitive internal URLs.
Keep human confirmation for payments, deletion, bulk submission, account changes, and external publishing.
Record verification date and scope.
Allow skills to expire after site changes and require revalidation.
Do not make bypassing risk controls or platform limits a goal.

In other words, domain skills make agents steadier. They do not give agents unlimited permission.

Conclusion

The domain skills mechanism in browser-harness shows one thing: AI browser automation cannot rely only on the model improvising at runtime.

A usable browser agent needs at least three layers:

Low-level control: screenshots, clicks, input, downloads, CDP, HTTP.
Site-level knowledge: API priority, stable selectors, component traps, login boundaries.
Human safety rules: do not give credentials to the model, confirm high-risk actions, and do not write sensitive information into skills.

domain skills fill the second layer. They let an agent enter a web task with verified experience instead of rediscovering everything every time.

References:

browser-harness domain skills: https://github.com/browser-use/browser-harness/tree/main/agent-workspace/domain-skills
Amazon product-search skill: https://github.com/browser-use/browser-harness/blob/main/agent-workspace/domain-skills/amazon/product-search.md
ArXiv scraping skill: https://github.com/browser-use/browser-harness/blob/main/agent-workspace/domain-skills/arxiv/scraping.md
GitHub scraping skill: https://github.com/browser-use/browser-harness/blob/main/agent-workspace/domain-skills/github/scraping.md
LinkedIn invitation-manager skill: https://github.com/browser-use/browser-harness/blob/main/agent-workspace/domain-skills/linkedin/invitation-manager.md
Shopify admin skill: https://github.com/browser-use/browser-harness/blob/main/agent-workspace/domain-skills/shopify-admin/README.md
Browser Use Cloud skill: https://github.com/browser-use/browser-harness/blob/main/agent-workspace/domain-skills/browser-use-cloud/cloud.md

browser-harness, Playwright, and Puppeteer: which browser automation tool should you choose?

Sun, 24 May 2026 17:51:28 +0800

In browser automation and automated testing, Playwright and Puppeteer are two of the most commonly compared tools. Both can control browsers, click pages, extract content, generate screenshots or PDFs, and both are closely related to Chrome DevTools Protocol.

Once browser-use/browser-harness is added to the picture, the question is no longer simply “which testing framework is stronger.” It becomes a comparison between two kinds of tools:

Playwright / Puppeteer: tools for engineers to write deterministic scripts.
browser-harness: a tool for AI agents to operate real browsers.

The first group fits testing, scraping, and engineered automation. The second is closer to a browser control layer for agents such as Claude Code, Codex CLI, and Gemini.

The relationship between Playwright and Puppeteer

Puppeteer was originally launched by the Google Chrome team and naturally focuses on Chromium and Chrome automation. Its API is concise, the ecosystem is mature, and it is especially convenient for screenshots, PDF generation, page scraping, and lightweight automation around Chrome.

Playwright is maintained by Microsoft, and its team has deep historical links to early Puppeteer work. It absorbed many lessons from Puppeteer and added stronger cross-browser support, auto-waiting, context isolation, test reports, and debugging tools.

In short:

If you only need lightweight Chrome-based tasks, Puppeteer is still very pleasant to use.
If you are doing cross-browser E2E tests, complex SPA automation, or team-level test engineering, Playwright is usually the better fit.

Core differences

Dimension	Puppeteer	Playwright
Maintainer	Google	Microsoft
Browser support	Mainly Chrome / Chromium	Chromium, Firefox, WebKit
Language support	Mainly JavaScript / TypeScript	JavaScript / TypeScript, Python, Java, .NET
Auto-waiting	More explicit waiting	Strong Locator and auto-waiting
Context isolation	Supported, but less central	Excellent BrowserContext workflow
Tooling	Simple, mature, foundational	Codegen, Trace Viewer, reports
Typical use	Chrome automation, screenshots, PDF, lightweight scraping	Cross-browser E2E tests, complex frontend automation

Browser support

Puppeteer is strongest with Chrome. It integrates tightly with Chromium. If your goal is to control Chrome, generate PDFs, take screenshots, or run simple scraping tasks, Puppeteer has a low mental overhead.

Playwright is stronger for cross-browser work. It natively supports Chromium, Firefox, and WebKit. WebKit is especially important because many Safari-related issues cannot be detected through Chrome alone. For applications that need coverage across desktop, mobile, and multiple browser engines, Playwright is the better main tool.

This is the first decision boundary: if you only care about Chrome, Puppeteer is fine. If you are serious about cross-browser testing, choose Playwright first.

Auto-waiting and stability

The most annoying part of browser automation is often not “how to click,” but whether the page is ready. An element may not be attached to the DOM, may be covered, may still be animating, or may still be disabled.

In Puppeteer, you often write:

1
2

await page.waitForSelector('#submit-btn');
await page.click('#submit-btn');

This works, but engineers must think through the waiting logic themselves. The more complex the page, the more likely the script will accumulate waitForSelector, waitForTimeout, and retry logic.

Playwright’s Locator and auto-waiting mechanism is more complete:

`1`	`await page.locator('#submit-btn').click();`

Before clicking, Playwright checks whether the element is visible, actionable, stable, and not covered, then retries within a reasonable time. This matters a lot for modern React, Vue, and Next.js applications with heavy asynchronous rendering, and it reduces flaky tests.

Multi-account workflows and context isolation

If you need to simulate multiple users, or let many tasks share one browser process while isolating Cookie, LocalStorage, and Session, BrowserContext matters.

Puppeteer also supports context isolation, but Playwright makes it a core capability. You can quickly create multiple independent contexts inside one browser instance. Each context behaves like a clean browser environment without repeatedly starting full browser processes.

This is useful for:

Multi-account concurrent tests.
Multi-role workflow tests.
Ecommerce, messaging, and collaborative document scenarios.
Scraping tasks that need isolated Cookie and login state.

Tooling differences

Playwright is the more engineering-oriented option. It includes many tools used in test development:

codegen: operate on a webpage and generate scripts automatically.
Trace Viewer: replay screenshots, DOM snapshots, network requests, and console logs after failures.
Test Runner: assertions, parallelism, retries, reports, and project matrices.
Locator: element selection by text, role, label, test id, and CSS.

Puppeteer is more like a lightweight browser control library. It is not bloated, its API is direct, and it is easy to embed in scripts, server-side jobs, and custom automation flows.

If you are building an enterprise-grade test system, Playwright’s tooling saves a lot of work. If you only need a Node.js script to convert webpages to PDFs or take scheduled screenshots, Puppeteer may be cleaner.

Where browser-harness fits

browser-harness is not the same kind of tool as Playwright or Puppeteer.

Playwright and Puppeteer mostly assume that humans write scripts. Engineers choose selectors, waiting conditions, assertions, and exception handling. They pursue determinism: the same script should produce the same result under the same page state.

browser-harness mostly assumes that an AI agent operates the browser. Its goal is not to provide a huge high-level API, but to connect to real Chrome through CDP and expose screenshots, coordinate clicks, DOM, network requests, and helpers to the agent. The agent can observe the page, decide the next step, add helpers when capabilities are missing, and turn site experience into skills.

That makes it better for open-ended tasks:

Log in to a backend and download invoices.
Fill a group of forms in an internal system.
Handle OA or SaaS pages that change often.
Explore a page according to a user goal instead of running a fixed script.
Give tools such as Claude Code and Codex CLI browser operation capability.

Three-way comparison

Dimension	Puppeteer	Playwright	browser-harness
Target user	Engineers	Engineers and test teams	AI Agent
Main goal	Control Chrome	Stable cross-browser automation	Let agents operate real browsers
Script style	Hand-written JS/TS automation	Scripts plus test framework	User gives a goal, agent executes steps
Element targeting	CSS, XPath, DOM API	Locator, text, role, CSS	Screenshots, coordinates, DOM, CDP
Waiting	More manual control	Strong auto-waiting	Agent observes and adjusts
Browser environment	Usually automated browser	Usually test browser	Often real Chrome
Best fit	Chrome scripts, screenshots, PDF, lightweight scraping	E2E tests, cross-browser validation, complex SPA	AI assistants, open web tasks, real-account workflows

Code feel

Puppeteer feels closer to directly controlling Chrome:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');

  await page.waitForSelector('#submit-btn');
  await page.click('#submit-btn');

  await browser.close();
})();

Playwright emphasizes Locator and auto-waiting:

const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');

  await page.locator('#submit-btn').click();

  await browser.close();
})();

browser-harness feels completely different. You usually do not write a full script. You give a goal inside an agent environment:

`1`	`Open the admin panel, download last month’s invoice, and organize it for reimbursement.`

The agent then repeatedly uses browser-harness to:

Take screenshots and understand the current page.
Click a coordinate or locate an element.
Enter text, upload files, and download files.
Decide how to close popups.
Add helper code when something is missing.
Turn reusable flows into domain skills.

This is not the style of traditional test scripts. It is the workflow of a browser agent.

How to choose

Choose Puppeteer when:

The project mainly runs in Node.js.
You only need Chrome or Chromium.
The task is screenshot, PDF generation, simple page scraping, or lightweight automation.
You want a simple API, fewer dependencies, and more manual control.
You rely deeply on Chrome DevTools Protocol.

Choose Playwright when:

You are building standard UI automation or E2E tests.
You need Chromium, Firefox, and WebKit coverage.
Your team’s main language may be Python, Java, or C#.
The page is a complex SPA with many asynchronous states and potential flaky tests.
You need codegen, Trace Viewer, test reports, and parallel testing.

Choose browser-harness when:

You are building or using AI agents.
You want the model to operate a real browser like a human.
The task steps are not fixed and require page-by-page judgment.
The target site changes often, or has many popups, iframes, and shadow DOM.
You want real web workflows handled by Claude Code, Codex CLI, or similar tools.

Conclusion

Playwright and Puppeteer are browser automation tools whose core goal is to let humans write reliable scripts. Puppeteer is lighter and closer to Chrome. Playwright is more complete and better for cross-browser testing and complex frontend applications.

browser-harness is a different direction. It is not designed to replace Playwright or Puppeteer for tests. It is designed to let AI agents control real browsers. It gives up some traditional script determinism in exchange for stronger adaptability in open-ended tasks.

So the answer is not to pick only one. Choose by task layer:

Test engineering: prefer Playwright.
Lightweight Chrome scripts: Puppeteer fits well.
AI agents doing work on the web: look at browser-harness.

References:

browser-use/browser-harness: https://github.com/browser-use/browser-harness
Playwright documentation: https://playwright.dev/
Puppeteer documentation: https://pptr.dev/
Chrome DevTools Protocol: https://chromedevtools.github.io/devtools-protocol/

What is browser-harness? A browser automation tool that lets AI agents control real Chrome

Sun, 24 May 2026 17:19:54 +0800

browser-use/browser-harness is a browser control tool for AI agents. Its goal is not to build another heavy automation framework, but to connect large language models directly to real Chrome through CDP, so they can browse pages, click, take screenshots, download files, upload files, and fill forms.

The README describes the project as a thin, editable CDP harness for letting LLMs connect to a real browser. When a task lacks a helper, the agent can add code during execution and turn reusable experience into domain skills.

This is worth watching because the browser is still the entry point for many real workflows: admin panels, SaaS dashboards, ecommerce sites, recruiting platforms, CRMs, reimbursement systems, cloud consoles, and document platforms. Many of them do not expose stable APIs, or their API permissions are harder to obtain than webpage access. Giving an agent reliable browser control is a way to fill that last mile of automation.

What browser-harness is

Structurally, browser-harness is closer to a browser runtime for agents than a browser extension for manual users.

Its core ideas are:

Connect directly to Chrome or Chromium.
Control pages through a CDP WebSocket.
Let agents combine screenshots, coordinate clicks, DOM inspection, network requests, and raw CDP.
Put task-specific helpers in agent-workspace/agent_helpers.py.
Store site-specific experience in agent-workspace/domain-skills/.
Keep the core thin instead of turning it into a large automation platform.

The README says the core architecture is roughly four core files and about 1,000 lines of code, covering install.md, SKILL.md, src/browser_harness/, agent-workspace/agent_helpers.py, and agent-workspace/domain-skills/.

The point is not to ship built-in support for every website. The point is to give the agent an operation layer close enough to a real browser, so it can fill in missing capabilities for the task at hand.

How it differs from traditional browser automation

Traditional browser automation usually revolves around testing frameworks such as Playwright, Selenium, or Puppeteer. They are good for deterministic scripts: open a page, locate an element, click it, and assert the result.

browser-harness targets a different kind of work. A user gives a goal, and the agent explores the page, judges the state, handles popups, adds helpers, and reuses site knowledge. It emphasizes adaptation during interaction.

The difference can be summarized like this:

Playwright is better when humans write scripts and agents run them.
browser-harness is better when agents look at the page and act step by step.
Traditional automation favors fixed flows.
browser-harness favors open-ended tasks.
Traditional scripts often depend on selectors.
browser-harness encourages screenshots first, visible UI actions next, and DOM or CDP when needed.

This does not mean it replaces Playwright. For stable tests, Playwright is still more mature. browser-harness is valuable because it turns real webpages into an environment an agent can operate, especially when page structure is complex, steps are not fixed, and situational judgment matters.

Why real Chrome matters

Many browser-agent tools use isolated headless browsers. That is simple to deploy and good for batch jobs, but it does not always reuse the user’s real working environment: login state, extensions, history, bookmarks, and daily browser setup.

browser-harness supports local Chrome and the Browser Use cloud browser. For local browsers, it offers two approaches:

Use chrome://inspect/#remote-debugging to allow the current Chrome instance to be connected.
Start an isolated profile with --remote-debugging-port=9222 --user-data-dir=....

If you want an agent to help with tasks inside real accounts, the docs lean toward the first approach because it reuses everyday Chrome login state, extensions, and bookmarks. For unattended automation, or when you do not want popups to interrupt work, an isolated profile or cloud browser is usually safer.

The trade-off is clear: real Chrome is closer to the user’s workflow, but the security boundary is more sensitive. An isolated browser is easier to control, but login and environment setup must be handled again.

Editable helpers and domain skills

The most interesting part of browser-harness is that it designs “what the agent learns” into the project structure.

agent-workspace/agent_helpers.py stores helpers that are created during tasks. For example, if an agent needs to upload a file and the existing tools are not enough, it can add a stable upload helper. The next time it sees a similar page, it does not have to start from scratch.

agent-workspace/domain-skills/ stores site-level experience. The README mentions areas such as LinkedIn outreach, Amazon ordering, and reimbursement systems. The project recommends letting agents generate these skills from real tasks instead of hand-writing them, because they should reflect actual page behavior.

This fits browser automation well. The hard part is often not “how to click a button,” but:

How a website redirects after login.
Which popups block the main flow.
Which selectors are stable and which are temporary class names.
How uploads, downloads, iframes, shadow DOM, and cross-origin components behave.
What hidden waits and asynchronous states exist in a specific backend.

If this knowledge only stays in one run log, it is quickly lost. Turning it into domain skills gives the agent a chance to improve over time.

Suitable scenarios

browser-harness is better suited for:

Operating real web admin panels for users.
Completing repeated flows in systems without APIs.
Personal or enterprise web tasks that depend heavily on login state.
Complex interactions where screenshots are needed to judge page state.
Agents that need to add tools and site knowledge while running.
Multiple sub-agents each using an isolated browser.
Researching browser-agent runtime design.

Concrete examples include organizing web tables, submitting internal forms, downloading invoices, uploading files, handling reimbursement workflows, checking order status, configuring SaaS dashboards, and extracting information from logged-in pages.

If the task is only to fetch static pages, a browser may not be needed. The project’s own SKILL.md also notes that static pages can often be fetched through HTTP in bulk. Browsers should be reserved for tasks that truly need page state, login state, and interaction.

Risks to watch

Letting an AI agent control real Chrome is powerful, but risky.

First, the permission boundary must be clear. Real Chrome may contain email, payment dashboards, cloud consoles, company systems, and personal accounts. Once an agent can operate the browser, it effectively has access to part of those webpage permissions.

Second, do not hand credentials to the model. For login pages, payment verification, and second confirmations, the user should handle the sensitive step. The agent can wait for login to finish, but it should not read or enter passwords, verification codes, or payment details from screenshots.

Third, automation is not the same as delegation. Many web tasks look simple but may involve risk controls, mistaken clicks, data deletion, bulk submissions, or irreversible operations. Start with read-only, low-risk, reversible workflows.

Fourth, domain skills should not leak private data. Site knowledge can be shared, but account names, internal URLs, customer data, coordinate logs, and one-off task details should not be written into skills.

Fifth, choose the browser connection mode carefully. Reusing daily Chrome is convenient when login state matters. For long-running automation, an isolated profile or cloud browser is more controllable.

Why it matters for AI agent tools

browser-harness represents a pragmatic direction for agent tooling: build less platform, and give the model a direct interface to the real environment.

Many agents fail at two ends. On one end, the model can reason but cannot touch the real page. On the other, automation frameworks are powerful but require humans to hard-code the flow. browser-harness tries to connect the two: the browser holds real-world state, while the agent observes, decides, and adds tools.

That is also the meaning of a self-improving harness. It does not mean the agent magically becomes smarter. It means reusable operation experience is placed into the project structure, so the next task can avoid some of the same detours.

For developers, its value is mainly in three areas:

A browser control layer for personal agents.
A reference for studying browser automation and agent workflows.
An experimental framework for turning web workflows into reusable skills.

It is not the answer to every browser automation problem, but it points in a clear direction: when agents truly help people do work, the tool layer should not only call APIs. It should also understand and operate the web interfaces people use every day.

Conclusion

browser-use/browser-harness is interesting not because it wraps many advanced features, but because it brings several key browser-agent questions into focus: real Chrome, CDP, screenshot-driven control, editable helpers, site skill accumulation, and user permission boundaries.

If you are writing stable end-to-end tests, Playwright or Selenium is still a better fit. If you want agents such as Codex or Claude Code to handle real webpage tasks, browser-harness offers an entry point that matches how agents work.

In practice, start with low-risk tasks: let it read pages, take screenshots, and extract information first. Then gradually try clicking and submitting. Once it can reliably understand page state, you can consider giving it longer workflows.

References:

GitHub project: https://github.com/browser-use/browser-harness
README: https://github.com/browser-use/browser-harness/blob/main/README.md
Installation guide: https://github.com/browser-use/browser-harness/blob/main/install.md
Usage guide: https://github.com/browser-use/browser-harness/blob/main/SKILL.md

What Is CloakBrowser? A More Realistic Browser for Playwright and Puppeteer

Tue, 19 May 2026 10:56:50 +0800

CloakHQ/CloakBrowser is an open source project for browser automation. It is not just a Playwright configuration file or a small JavaScript patch. The project is built around a custom Chromium binary, aiming to make browser fingerprints, WebGL, Canvas, audio, fonts, GPU, screen data, WebRTC, and network timing look closer to a normal browser environment.

Project URL: https://github.com/CloakHQ/CloakBrowser

At the time of writing, the GitHub API showed about 15k stars, Python as the main language, and an MIT license. The README positions it very directly: a Stealth Chromium launcher that can replace the default Playwright or Puppeteer browser launcher.

What Problem Does It Solve

Many automation scripts expose obvious automation signals when they run in a regular Headless Chromium environment, for example:

navigator.webdriver.
Headless user agent traces.
Unnatural plugin, font, screen, and GPU fingerprints.
CDP behavior that does not match real user input.
Temporary profiles without normal browsing traces.

CloakBrowser moves part of this work into the Chromium source and binary layer, instead of relying only on runtime configuration or JavaScript patches. For Playwright users, the API still feels close to familiar browser automation, but the underlying browser is replaced with the custom build provided by the project.

This type of tool is suitable for compliant automation testing, site compatibility checks, anti-abuse system self-testing, and agent browser environment experiments. It should not be used for unauthorized access, account abuse, bypassing platform risk controls, or violating service terms.

Basic Usage

Python installation:

`1`	`pip install cloakbrowser`

JavaScript / Node.js installation:

`1`	`npm install cloakbrowser playwright-core`

The Python example in the README looks close to Playwright:

from cloakbrowser import launch

browser = launch()
page = browser.new_page()
page.goto("https://protected-site.com")
browser.close()

The JavaScript usage is also straightforward:

import { launch } from 'cloakbrowser';

const browser = await launch();
const page = await browser.newPage();
await page.goto('https://protected-site.com');
await browser.close();

Browser Profile Manager

CloakBrowser also provides a Browser Profile Manager. It is meant for managing browser profiles, testing environments, and repeated automation tasks more conveniently.

`1`	`docker run -p 8080:8080 -v cloakprofiles:/data cloakhq/cloakbrowser-manager`

After starting it, open:

`1`	`http://localhost:8080`

The value of a profile manager is that the browser environment does not have to be a disposable temporary profile every time. For long-running tests, compatibility checks, and agent experiments, stable profiles are often easier to debug.

How It Differs From Regular Playwright

Regular Playwright focuses on reliable browser control. CloakBrowser focuses on making the browser environment itself look more natural.

In practice, the difference is:

Playwright provides the automation API.
CloakBrowser provides a custom browser runtime.
Playwright is suitable for general testing and automation.
CloakBrowser is more focused on realistic browser behavior and fingerprint consistency.

This does not mean CloakBrowser can magically solve all detection problems. Websites can still use behavior, frequency, account reputation, network environment, and business rules to judge risk.

What To Watch Out For

First, compliance matters. A more realistic automation environment does not mean unrestricted use. Automated access should respect authorization, rate limits, robots or platform rules, and service terms.

Second, the project depends on a custom Chromium build. Teams should pay attention to version compatibility, security updates, and whether the binary source is acceptable for production use.

Third, realistic browser behavior is only one part of the picture. If the script performs unnatural operations, sends requests too frequently, or uses accounts in abnormal ways, the result will still be risky.

Who It Is For

CloakBrowser is more suitable for developers and teams already using Playwright, Puppeteer, browser agents, QA automation, or web compatibility testing. It is less suitable for users who just want a no-code browser automation product.

Summary

CloakBrowser is interesting because it moves browser automation from “just control a headless browser” toward “use a browser environment closer to real users.” For testing, agent experiments, and controlled research, it is worth watching. For real-world use, the important boundary is still compliance, authorization, and risk control.

Playwright CLI Video Recording: Recording, Chapter Markers, Overlays, and Debugging Tradeoffs

Wed, 15 Apr 2026 08:22:45 +0800

If you want to record browser automation sessions as video for debugging, documentation, or proof of work, Playwright CLI already provides a fairly direct workflow. It produces WebM video using the VP8/VP9 codec.

This article follows the official video-recording reference and focuses on the parts that matter most in practice: the basic recording flow, chapter markers, full hero-script recording, the Overlay API, and the difference between video and tracing. The command lines, code snippets, and parameter details are preserved from the reference.

01 Basic Recording Flow

The basic pattern is simple: open the browser, start recording, perform actions, then stop and save.

# Open browser first
playwright-cli open

# Start recording
playwright-cli video-start demo.webm

# Add a chapter marker for section transitions
playwright-cli video-chapter "Getting Started" --description="Opening the homepage" --duration=2000

# Navigate and perform actions
playwright-cli goto https://example.com
playwright-cli snapshot
playwright-cli click e1
# Add another chapter
playwright-cli video-chapter "Filling Form" --description="Entering test data" --duration=2000
playwright-cli fill e2 "test input"

# Stop and save
playwright-cli video-stop

These commands already cover the most common recording flow. video-chapter is useful for inserting chapter cards between stages so the final video is easier to follow.

02 Best Practices

1. Use Descriptive Filenames

If the video is meant for other people or for later review, the filename should include enough context to make it understandable at a glance.

1
2
3

# Include context in filename
playwright-cli video-start recordings/login-flow-2024-01-15.webm
playwright-cli video-start recordings/checkout-test-run-42.webm

2. Record Entire Hero Scripts

The official recommendation is that when a video is for a user or serves as proof of work, it is best to turn the scenario into a code snippet and execute it with run-code. That gives you better control over pacing, pauses, and annotations in the video. The reference also notes that Playwright now includes APIs designed specifically for this kind of recording flow.

The suggested process is:

First perform the scenario with the CLI and note all locators and actions. You will need those locators later if you want their bounding boxes for highlight overlays.
Create a dedicated script file for the video and write it in the style shown below. Use pressSequentially with delay for smoother typing, and add pauses where they feel natural.
Use playwright-cli run-code --filename your-script.js.

Important: Overlays are pointer-events: none — they do not interfere with page interactions. You can safely keep sticky overlays visible while clicking, filling, or performing any actions on the page.

async page => {
  await page.screencast.start({ path: 'video.webm', size: { width: 1280, height: 800 } });
  await page.goto('https://demo.playwright.dev/todomvc');
  // Show a chapter card — blurs the page and shows a dialog.
  // Blocks until duration expires, then auto-removes.
  // Use this for simple use cases, but always feel free to hand-craft your own beautiful
  // overlay via await page.screencast.showOverlay().
  await page.screencast.showChapter('Adding Todo Items', {
    description: 'We will add several items to the todo list.',
    duration: 2000,
  });
  // Perform action
  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Walk the dog', { delay: 60 });
  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
  await page.waitForTimeout(1000);

  // Show next chapter
  await page.screencast.showChapter('Verifying Results', {
    description: 'Checking the item appeared in the list.',
    duration: 2000,
  });
  // Add a sticky annotation that stays while you perform actions.
  // Overlays are pointer-events: none, so they won't block clicks.
  const annotation = await page.screencast.showOverlay(`
    <div style="position: absolute; top: 8px; right: 8px;
      padding: 6px 12px; background: rgba(0,0,0,0.7);
      border-radius: 8px; font-size: 13px; color: white;">
      ✓ Item added successfully
    </div>
  `);
  // Perform more actions while the annotation is visible
  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Buy groceries', { delay: 60 });
  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
  await page.waitForTimeout(1500);

  // Remove the annotation when done
  await annotation.dispose();
  // You can also highlight relevant locators and provide contextual annotations.
  const bounds = await page.getByText('Walk the dog').boundingBox();
  await page.screencast.showOverlay(`
    <div style="position: absolute;
      top: ${bounds.y}px;
      left: ${bounds.x}px;
      width: ${bounds.width}px;
      height: ${bounds.height}px;
      border: 1px solid red;">
    </div>
    <div style="position: absolute;
      top: ${bounds.y + bounds.height + 5}px;
      left: ${bounds.x + bounds.width / 2}px;
      transform: translateX(-50%);
      padding: 6px;
      background: #808080;
      border-radius: 10px;
      font-size: 14px;
      color: white;">Check it out, it is right above this text
    </div>
  `, { duration: 2000 });
  await page.screencast.stop();
}

The value of this script is not only that it records the flow, but that it makes the video easier to understand: chapter cards handle transitions, pressSequentially makes typing look natural, and showOverlay adds explanation, highlights, and context.

The reference closes this section with a short reminder: Embrace creativity, overlays are powerful.

03 Overlay API Summary

When recording video, the Overlay API is especially useful for section transitions, local callouts, and sticky annotations. The official summary is:

Method	Use Case
`page.screencast.showChapter(title, { description?, duration?, styleSheet? })`	Full-screen chapter card with blurred backdrop — ideal for section transitions
`page.screencast.showOverlay(html, { duration? })`	Custom HTML overlay — use for callouts, labels, highlights
`disposable.dispose()`	Remove a sticky overlay added without duration
`page.screencast.hideOverlays()` / `page.screencast.showOverlays()`	Temporarily hide/show all overlays

If your goal is to turn automation into a video people can comfortably watch, this API set is one of the most valuable pieces to learn first.

04 Tracing vs Video

The official documentation makes the difference between the two very clear:

Feature	Video	Tracing
Output	WebM file	Trace file (viewable in Trace Viewer)
Shows	Visual recording	DOM snapshots, network, console, actions
Use case	Demos, documentation	Debugging, analysis
Size	Larger	Smaller

A simple way to think about it:

video is better for demos, delivery, and reviewing what a user would see
tracing is better for debugging, inspecting action details, and analyzing execution context

They are not replacements for each other. Each serves a different purpose.

05 Limitations

The reference also points out two practical limitations:

Recording adds slight overhead to automation
Large recordings can consume significant disk space

So while video recording is very useful, it does add some runtime overhead, and longer recordings can grow large on disk.

06 Quick Summary

If you only want the essentials, remember these points:

video-start / video-stop are the core commands for recording
video-chapter adds section transitions and makes demos easier to follow
More advanced recording scenarios are best written as scripts and executed with run-code
showOverlay and showChapter can significantly improve video readability
video is best for demos, while tracing is best for debugging

If your workflow already includes automation demos, acceptance evidence, or proof-of-work recordings, video recording is a very worthwhile part of Playwright CLI to add.

References

Playwright CLI video-recording reference: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/video-recording.md
Playwright CLI project homepage: https://github.com/microsoft/playwright-cli

Playwright CLI Session Management: Multiple Browser Sessions, Isolation, Persistence, and Cleanup

Wed, 15 Apr 2026 08:15:12 +0800

If you use Playwright CLI for automation, you will quickly run into a practical question: can you open multiple browser sessions at the same time without them interfering with each other? The answer is yes, and Playwright CLI already makes this mechanism quite straightforward.

Following the official session-management reference, this article focuses on its most practical pieces: named sessions, session isolation, persistent profiles, concurrent patterns, and common cleanup commands. The command lines and command block explanations are preserved from the reference content.

01 Named Browser Sessions

The official recommendation is to use the -s parameter to isolate different browser contexts:

# Browser 1: Authentication flow
playwright-cli -s=auth open https://app.example.com/login

# Browser 2: Public browsing (separate cookies, storage)
playwright-cli -s=public open https://example.com

# Commands are isolated by browser session
playwright-cli -s=auth fill e1 "user@example.com"
playwright-cli -s=public snapshot

The key point here is that different session names map to different browser contexts. You can use auth for the sign-in flow and public for anonymous browsing, and they will not share cookies or local state.

02 What Does Browser Session Isolation Separate?

Each browser session maintains the following items independently:

Cookies
LocalStorage / SessionStorage
IndexedDB
Cache
Browsing history
Open tabs

That means if you sign in to a site in the auth session, it will not automatically affect the public session. This is especially important for multi-account testing, login-state verification, and anonymous-vs-authenticated comparisons.

The official documentation groups the most commonly used session-management commands together:

# List all browser sessions
playwright-cli list

# Stop a browser session (close the browser)
playwright-cli close                 # stop the default browser
playwright-cli -s=mysession close   # stop a named browser

# Stop all browser sessions
playwright-cli close-all

# Forcefully kill all daemon processes (for stale/zombie processes)
playwright-cli kill-all

# Delete browser session user data (profile directory)
playwright-cli delete-data              # delete default browser data
playwright-cli -s=mysession delete-data # delete named browser data

You can think of them as three kinds of operations:

list: see which sessions currently exist
close / close-all / kill-all: stop sessions or clean up stuck browser processes
delete-data: remove the user data directory for a specific session

If you just want to close a browser, close is usually the first choice. If leftover or zombie processes have already appeared, kill-all is the better fit.

04 Set a Default Session with an Environment Variable

If you do not want to repeat -s=mysession on every command, the official docs also provide an environment-variable approach:

1
2

export PLAYWRIGHT_CLI_SESSION="mysession"
playwright-cli open example.com  # Uses "mysession" automatically

After that, when you do not explicitly specify -s, the command will use mysession as the default browser session.

05 Common Pattern: Concurrent Scraping

The reference gives a very typical concurrent-scraping example:

#!/bin/bash
# Scrape multiple sites concurrently

# Start all browsers
playwright-cli -s=site1 open https://site1.com &
playwright-cli -s=site2 open https://site2.com &
playwright-cli -s=site3 open https://site3.com &
wait

# Take snapshots from each
playwright-cli -s=site1 snapshot
playwright-cli -s=site2 snapshot
playwright-cli -s=site3 snapshot

# Cleanup
playwright-cli close-all

This pattern works well when you want to open multiple sites at once, capture each page state, and then clean everything up together. Because each site runs in an independent session, they do not contaminate each other’s local state.

06 Common Pattern: A/B Test Sessions

Another common scenario is comparing different experiment variants at the same time:

# Test different user experiences
playwright-cli -s=variant-a open "https://app.com?variant=a"
playwright-cli -s=variant-b open "https://app.com?variant=b"

# Compare
playwright-cli -s=variant-a screenshot
playwright-cli -s=variant-b screenshot

This style is great for A/B page comparisons because the two variants run in separate sessions, making screenshots and state checks easier to manage independently.

07 Persisting Browser Profiles

The official documentation specifically points out that browser profiles are stored only in memory by default.

If you want to persist a browser profile to disk, add --persistent when running open:

# Use persistent profile (auto-generated location)
playwright-cli open https://example.com --persistent

# Use persistent profile with custom directory
playwright-cli open https://example.com --profile=/path/to/profile

This capability is useful when you need to reuse login state, local cache, or an extension-debugging environment over the long term. When repeatedly debugging the same site, a persistent profile is often much more efficient than starting from scratch every time.

08 The Default Browser Session

If -s is not explicitly provided, the command uses the default browser session:

# These use the same default browser session
playwright-cli open https://example.com
playwright-cli snapshot
playwright-cli close  # Stops default browser

In other words, commands without -s are executed continuously within the same default session.

In addition to the session name, the official docs also show several common startup configuration patterns:

# Open with config file
playwright-cli open https://example.com --config=.playwright/my-cli.json

# Open with specific browser
playwright-cli open https://example.com --browser=firefox

# Open in headed mode
playwright-cli open https://example.com --headed

# Open with persistent profile
playwright-cli open https://example.com --persistent

These parameters can be combined with session management. For example, you can make one named session always run in firefox, or make a specific session always launch in headed mode for easier manual inspection.

10 Best Practices from the Official Docs

The reference lists three practical best practices.

1. Use Meaningful Session Names

# GOOD: Clear purpose
playwright-cli -s=github-auth open https://github.com
playwright-cli -s=docs-scrape open https://docs.example.com

# AVOID: Generic names
playwright-cli -s=s1 open https://github.com

Session names should ideally communicate their purpose directly. Names like github-auth and docs-scrape make later script maintenance much clearer.

2. Clean Up Promptly After Use

# Stop browsers when done
playwright-cli -s=auth close
playwright-cli -s=scrape close

# Or stop all at once
playwright-cli close-all

# If browsers become unresponsive or zombie processes remain
playwright-cli kill-all

If you do not close the browser after a task finishes, the session and background processes will remain. That may not seem serious in the short term, but once tasks pile up, the environment can become messy very quickly.

3. Remove Stale Browser Data

1
2

# Remove old browser data to free disk space
playwright-cli -s=oldsession delete-data

When some old sessions are no longer needed, deleting their data directories saves disk space and also helps avoid accidentally reusing outdated state later.

11 Quick Summary

If you only want the essentials, remember these points:

-s=<name> creates and uses an independent browser session
Different sessions isolate cookies, different kinds of storage, cache, history, and tabs
close-all is useful for unified shutdown, while kill-all is useful for cleaning up abnormal leftover processes
--persistent writes the profile to disk and is useful for long-term state reuse
Session names should be meaningful, and old data should be cleaned up regularly

If your workflow already includes reused login states, parallel multi-account work, A/B comparisons, or batch scraping, then session management is basically one of the most worthwhile pieces of Playwright CLI to learn first.

References

Playwright CLI session-management reference: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/session-management.md
Playwright CLI project homepage: https://github.com/microsoft/playwright-cli

Playwright CLI storage state: Save Login Sessions, Read Cookies, and Local Storage

Tue, 14 Apr 2026 22:19:55 +0800

If you use Playwright CLI for browser automation, storage state is one of the most useful features. Its job is simple: save the current login session and local browser state so you can reuse them later instead of logging in every time.

01 Save the current storage state

The most common workflow is to log in once, then export the current state to a file.

`1`	`playwright-cli storage-state save auth.json`

This command saves the current browser context state to auth.json. If you want to reuse a login session later, this is usually the first step.

02 Load an existing storage state

Once you already have a state file, you can load it directly at startup.

`1`	`playwright-cli --storage-state auth.json`

It launches the browser context with the state stored in auth.json. The usual purpose is to skip repeated login and jump straight into a signed-in environment.

03 View current cookies

If you only want to check which cookies exist in the current session, you can inspect them directly.

`1`	`playwright-cli cookies`

This command lists the cookies in the current context. It is useful when checking whether the login state exists or whether cookies were written successfully.

04 Set cookies

If you already have cookie data, you can inject it directly as well.

`1`	`playwright-cli cookies set '[{"name":"session","value":"abc","domain":"example.com","path":"/"}]'`

This is useful for auth debugging, reproducing a specific session, or injecting cookie conditions before a script runs.

05 Read localStorage

Some sites store login-related or frontend state not only in cookies, but also in localStorage.

`1`	`playwright-cli local-storage`

This command shows the localStorage content of the current page. It is especially useful when a page looks logged in but still behaves incorrectly.

06 Write localStorage

If you need to simulate specific frontend state, you can set it directly.

`1`	`playwright-cli local-storage set token abc123`

It writes the given key and value into localStorage. Common uses include injecting a token, a preference, or a frontend flag.

07 Read sessionStorage

sessionStorage is useful for checking temporary state tied to the current session.

`1`	`playwright-cli session-storage`

This command outputs the current page’s sessionStorage. If a page flow depends on one-time session data, this is a good place to inspect it.

08 Write sessionStorage

When needed, you can also set sessionStorage manually.

`1`	`playwright-cli session-storage set key value`

It is useful for reproducing page behavior that depends on temporary state, or for filling in fields required by an initialization step.

09 View IndexedDB

For heavier web apps, the most important local data may actually live in IndexedDB.

`1`	`playwright-cli indexed-db`

This command lets you inspect the current page’s IndexedDB data. It is worth checking first when you are dealing with complex SPAs, offline cache, or app-like local databases.

10 A practical workflow

If your goal is simply to reuse a login session reliably, the most practical flow is usually this:

Open the site and complete login manually.
Save the state with this command:

`1`	`playwright-cli storage-state save auth.json`

Load it directly in later runs:

`1`	`playwright-cli --storage-state auth.json`

If the page still behaves incorrectly after loading, continue by checking:

playwright-cli cookies
playwright-cli local-storage
playwright-cli session-storage
playwright-cli indexed-db

That sequence covers most cases where the restored state is incomplete.

11 What to watch out for

Three points matter most:

A storage state file is sensitive data. It may contain login cookies or tokens, so do not commit it casually.
Restoring cookies alone may not be enough. Many modern sites also depend on localStorage, sessionStorage, or IndexedDB.
State files do not stay valid forever. After cookie expiration, account changes, or environment changes, you usually need to generate them again.

12 Quick summary

If you only remember one sentence:

Playwright CLI storage state means saving the browser’s current state and reusing it in later tasks.

In practice, the most useful commands are these:

playwright-cli storage-state save auth.json
playwright-cli --storage-state auth.json
playwright-cli cookies
playwright-cli local-storage
playwright-cli session-storage
playwright-cli indexed-db

Save first, then load; if something still looks wrong, inspect cookies and the different local storage layers one by one. That is the most practical part of this reference.

References

Playwright CLI storage-state reference: https://github.com/microsoft/playwright-cli/blob/main/skills/playwright-cli/references/storage-state.md
Playwright CLI project page: https://github.com/microsoft/playwright-cli

Getting Started with Playwright CLI: Installation, Skills, Sessions, and Essential Commands

Sun, 12 Apr 2026 14:36:58 +0800

If you have been using Claude Code, GitHub Copilot, or other coding agents for browser automation, microsoft/playwright-cli is a tool worth watching. It is not the traditional kind of browser helper meant mainly for humans typing commands by hand. Instead, it is a Playwright CLI designed for coding agents, with an emphasis on lower token overhead, a lighter command interface, and integration with Skills-based workflows.

From the official README, the core idea behind Playwright CLI is very clear: compared with MCP, which can push large tool schemas and page structure into the model context, the CLI approach is more compact and better suited for agent workflows that constantly switch between large codebases, tests, and browser automation.

01 What Playwright CLI is

playwright-cli is an open-source Playwright command-line tool from Microsoft. The official description is “CLI for common Playwright actions.” It is mainly used for tasks like these:

Opening pages and driving the browser
Recording and generating Playwright code
Capturing page snapshots to get element references
Taking screenshots and exporting PDFs
Working with coding agents for test automation and web interaction

The current GitHub README is very explicit about its positioning: if you are using coding agents, the CLI is often a better fit than Playwright MCP; if you need persistent state, richer introspection, and longer-running agentic loops, MCP still has its place.

In other words, Playwright CLI feels more like a browser automation interface built for AI coding assistants, not just a tool for engineers to click around manually.

02 Where it stands out

1. It fits agent workflows better

The official README lists Token-efficient as a key feature. It does not force full-page data into the LLM context. Instead, it lets the agent operate the browser through shorter and more focused commands.

That matters a lot for coding agents. In real projects, an agent is not only driving the browser. It also has to read code, edit files, run tests, and inspect logs. If the browser interface itself consumes too much context, the overall workflow becomes less efficient.

2. It works well with Skills

The README specifically highlights playwright-cli install --skills. That shows Microsoft is not treating it as just another shell utility, but as something that can be consumed directly by Claude Code, GitHub Copilot, and similar agents through a Skills-based workflow.

If your setup already relies on Skills, Playwright CLI should slot in naturally.

3. Session management is fairly complete

Playwright CLI supports sessions. By default, the browser profile stays in memory, so cookies and storage state are preserved across multiple CLI calls within the same session. If you add --persistent, the profile can be saved to disk and reused across browser restarts.

That makes it much more practical than tools that simply open a browser for one command and then throw everything away. It is also a better fit for long debugging cycles and longer-running agent flows.

4. It includes a visual monitoring dashboard

The README provides playwright-cli show, which opens a dashboard for observing and controlling all running browser sessions. This is especially useful when an agent is running automation in the background, because you can step in, inspect progress, and help with debugging instead of flying blind.

03 Installation and requirements

According to the current GitHub README, the basic requirements for Playwright CLI are:

Node.js 18 or newer
Claude Code, GitHub Copilot, or another coding agent

The installation commands are:

1
2

npm install -g @playwright/cli@latest
playwright-cli --help

There is one easy mistake worth calling out:

The officially recommended package right now is @playwright/cli
Do not confuse it with the old deprecated npm package playwright-cli

So the package you actually want is the scoped package, not the older historical one.

04 How to start using it

1. Install skills

If you want a coding agent to use Playwright CLI directly, the official recommendation is to install the skills first:

`1`	`playwright-cli install --skills`

The README explicitly says that Claude Code, GitHub Copilot, and similar tools will use the locally installed skills.

2. Let the agent call the CLI directly

If you do not want to handle Skills first, you can also let the agent read the CLI help output directly:

1
2

Test the "add todo" flow on https://demo.playwright.dev/todomvc using playwright-cli.
Check playwright-cli --help for available commands.

The README calls this “Skills-less operation.” The idea is that even without preinstalled skills, the CLI can still describe itself well enough for an agent to use it.

3. Try a minimal flow manually

The README includes a TodoMVC example that works very well as a first hands-on demo:

playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli type "Water flowers"
playwright-cli press Enter
playwright-cli check e21
playwright-cli check e35
playwright-cli screenshot

This sequence is useful because it quickly shows how Playwright CLI works in practice:

open opens the page
type and press handle text input
check uses an element reference to toggle checkboxes
screenshot saves the result

05 `--headed`, sessions, and the monitoring dashboard

`--headed`

Playwright CLI is headless by default. If you want to see the browser window directly, you need to pass --headed when using open:

`1`	`playwright-cli open https://playwright.dev --headed`

This is especially helpful when debugging selectors, login flows, or any interaction that is easier to inspect visually.

sessions

The official README places a lot of emphasis on sessions. You can use different sessions to isolate different projects or sites:

1
2
3

playwright-cli open https://playwright.dev
playwright-cli -s=example open https://example.com --persistent
playwright-cli list

If you are letting an agent run over a longer period, you can also pass the session through an environment variable:

`1`	`PLAYWRIGHT_CLI_SESSION=todo-app claude .`

Useful session management commands include:

1
2
3

playwright-cli list
playwright-cli close-all
playwright-cli kill-all

In practice:

list shows all sessions
close-all closes all browsers gracefully
kill-all forcefully terminates all browser processes

Monitoring dashboard

If you want to see what the agent is actually doing in the browser, you can run:

`1`	`playwright-cli show`

According to the README, this dashboard has two main views:

Session grid: shows active sessions by workspace, with live preview, URL, and page title
Session detail: shows a live view of a selected session and lets you take over mouse and keyboard input

That means Playwright CLI is not only usable from the command line. It also has a fairly mature observability layer.

06 Which commands are worth memorizing first

If this is your first time using Playwright CLI, you do not need to memorize every command up front. These are the core ones worth learning first:

Pages and interaction

playwright-cli open [url]
playwright-cli goto <url>
playwright-cli click <ref>
playwright-cli fill <ref> <text>
playwright-cli type <text>
playwright-cli hover <ref>
playwright-cli press <key>

Getting page structure

playwright-cli snapshot
playwright-cli snapshot <ref>
playwright-cli snapshot --depth=N
playwright-cli eval <func> [ref]

snapshot is especially important because many later operations depend on element references stored as ref. In practice, you usually capture a snapshot first, then use the returned element identifiers for clicking, filling, checking, or taking screenshots.

Saving output

1
2

playwright-cli screenshot
playwright-cli pdf

Tabs

playwright-cli tab-list
playwright-cli tab-new [url]
playwright-cli tab-close [index]
playwright-cli tab-select <index>

07 Who should try it

Playwright CLI is especially worth trying in these kinds of scenarios:

You are using Claude Code, Copilot, or another coding agent for E2E testing
You want a lighter browser automation interface without pushing large page structures into model context
You want one browser session to persist across multiple commands
You want to monitor agent-driven web tasks through a dashboard while they run

If your main question is how to make browser automation work efficiently with coding agents, Playwright CLI will likely feel more natural than traditional manual debugging workflows.

Browser Automation on KnightLi Blog

How browser-harness domain skills keep AI agents from repeating browser automation mistakes

What domain skills are

They are not about blind clicking

They store site-level knowledge

Example: Amazon product search

Example: LinkedIn invitation management

Example: Shopify Admin

Example: Browser Use Cloud

Why this is more reliable than ad-hoc reasoning

How teams can use it

Boundaries to keep

Conclusion

browser-harness, Playwright, and Puppeteer: which browser automation tool should you choose?

The relationship between Playwright and Puppeteer

Core differences

Browser support

Auto-waiting and stability

Multi-account workflows and context isolation

Tooling differences

Where browser-harness fits

Three-way comparison

Code feel

How to choose

Conclusion

What is browser-harness? A browser automation tool that lets AI agents control real Chrome

What browser-harness is

How it differs from traditional browser automation

Why real Chrome matters

Editable helpers and domain skills

Suitable scenarios

Risks to watch

Why it matters for AI agent tools

Conclusion

What Is CloakBrowser? A More Realistic Browser for Playwright and Puppeteer

What Problem Does It Solve

Basic Usage

Browser Profile Manager

How It Differs From Regular Playwright

What To Watch Out For

Who It Is For

Summary

Playwright CLI Video Recording: Recording, Chapter Markers, Overlays, and Debugging Tradeoffs

01 Basic Recording Flow

02 Best Practices

1. Use Descriptive Filenames

2. Record Entire Hero Scripts

03 Overlay API Summary

04 Tracing vs Video

05 Limitations

06 Quick Summary

References

Playwright CLI Session Management: Multiple Browser Sessions, Isolation, Persistence, and Cleanup

01 Named Browser Sessions

02 What Does Browser Session Isolation Separate?

03 Commands Related to Browser Sessions

04 Set a Default Session with an Environment Variable

05 Common Pattern: Concurrent Scraping

06 Common Pattern: A/B Test Sessions

07 Persisting Browser Profiles

08 The Default Browser Session

09 Session-Related Startup Configuration

10 Best Practices from the Official Docs

1. Use Meaningful Session Names

2. Clean Up Promptly After Use

3. Remove Stale Browser Data

11 Quick Summary

References

Playwright CLI storage state: Save Login Sessions, Read Cookies, and Local Storage

01 Save the current storage state

02 Load an existing storage state

03 View current cookies

04 Set cookies

05 Read localStorage

06 Write localStorage

07 Read sessionStorage

08 Write sessionStorage

09 View IndexedDB

10 A practical workflow

11 What to watch out for

05 `--headed`, sessions, and the monitoring dashboard

`--headed`