Install Playwright Globally for AI Agents

A practical guide to configuring Playwright and CloakBrowser globally. Essential setup for AI coding agents to perform browser automation instantly.

If you use AI coding agents (like Antigravity or Claude) to write and run web automation scrapers, you've probably hit the browser installation loop. Every time the agent spawns a script inside a new scratch directory, it wastes several minutes running npm install playwright and downloading ~150MB+ browser binaries. It slows down execution, burns bandwidth, and inflates context token usage.

A simpler approach is to install Playwright, CloakBrowser, and their browser binaries globally on your machine once. Once cached, any local workspace or scratch script can link to and use them instantly, removing all setup overhead.

---

🗺️ Architecture Overview

Here is how the global module resolution and cached binaries work:

               +-------------------------------------------+
               |               LOCAL MACHINE               |
               |       (AI Agent / Execution Context)      |
               +---------------------+---------------------+
                                     |
                          [1] npm / pip install -g
                                     v
               +---------------------+---------------------+
                |         GLOBAL RUNTIME REGISTRIES         |
                |  - Node.js: AppData\Roaming\npm\          |
                |  - Python:  AppData\Local\Programs\...    |
               +---------------------+---------------------+
                                     |
                            [2] playwright install
                                     v
               +---------------------+---------------------+
                |          GLOBAL BROWSER BINARIES          |
                |  Path: AppData\Local\ms-playwright\       |
                |  - Chromium (v1228)                       |
                |  - Firefox (v1532)                        |
                |  - WebKit (v2311)                         |
               +---------------------+---------------------+
                                     |
                              [3] npm link / use
                                     v
               +---------------------+---------------------+
                |            PROJECT WORKSPACE              |
                |  - Links to globally installed packages   |
                |  - Runs instantly without downloading     |
               +-------------------------------------------+

---

🛠️ Step-by-Step Installation Guide

1. Node.js Environment Setup

First, install the testing runner and stealth browser globally using npm, and then fetch the browser binaries:

# Install Playwright test runner and CloakBrowser globally
npm install -g @playwright/test playwright cloakbrowser

# Download and register all browser binaries globally
npx playwright install

[!TIP] The browser binaries are downloaded to C:\Users\<User>\AppData\Local\ms-playwright and are automatically reused by any project using Playwright on your system.

How to Use Global Modules in Local Projects (npm link)

Modern Node.js (especially ES Modules) restricts loading libraries directly from NODE_PATH. To use your global packages in a local workspace or scratch directory, use the npm link command:

# Navigate to your workspace
cd C:\path\to\your\project

# Link the global modules locally
npm link cloakbrowser @playwright/test

---

2. Python Environment Setup

Install the libraries into your main Python environment using pip:

# Install python packages globally
pip install playwright cloakbrowser

# Install browser binaries for Python if needed
playwright install

---

🧪 Verification & Testing

JavaScript ES Module Test (test_global.mjs)

Create a file named test_global.mjs and verify both libraries can import and launch a headed browser:

import { chromium } from 'playwright';
import { launch } from 'cloakbrowser';

(async () => {
  console.log("Checking global playwright library resolution...");
  console.log("Playwright Chromium exists:", !!chromium);

  console.log("Checking global cloakbrowser resolution...");
  console.log("CloakBrowser launch function exists:", !!launch);

  console.log("Testing Chromium launch in headed mode...");
  const browser = await chromium.launch({ headless: false });
  const page = await browser.newPage();
  
  await page.goto('https://example.com');
  console.log("Page title:", await page.title());
  
  await page.waitForTimeout(2000);
  await browser.close();
  console.log("Test PASSED!");
})();

Run the script:

node test_global.mjs

Python Test

Verify the imports directly from the command line:

python -c "import cloakbrowser, playwright; print('Python CloakBrowser + Playwright are ready!')"

---

🧠 Why This Helps AI Coding Agents

1. Speed: Scripts execute in under 3 seconds instead of waiting minutes for npm install and binary pulls.

2. Bandwidth: Stops redownloading gigabytes of browser dependencies.

3. No Timeout Errors: Headed tests running in agentic mode are less likely to trigger shell timeouts while preparing their environment.