@romanmatena/browsermonitor
Advanced tools
Browser console, network, DOM monitoring for debugging and LLM workflows. Captures console, network, cookies, screenshot, DOM. HTTP API for LLM/scripts. WSL+Windows, Linux, Open/Join modes.
Browser console, network, DOM, and screenshot monitoring for debugging and LLM workflows.
What it is: Browser Monitor lets you capture the live state of a browser—console output, network requests, cookies, screenshot, and the current page DOM—and write it all to files. You (or an LLM agent) can then read those files instead of asking someone to copy-paste from DevTools or the browser.
Why it's useful: When debugging a frontend app or feeding context to an AI assistant, you need the real console, the real DOM, and the real network traffic. Manual copy-paste is slow and error-prone. This tool connects to Chrome via Puppeteer, records everything in one place, and exposes a simple "dump" so the next step is always "read the files" instead of "please open the browser and copy this."
Who needs it: Frontend and full-stack developers who debug in the browser; teams using LLM coding agents that need up-to-date DOM and network data; anyone who wants a repeatable way to snapshot browser state for logs, tests, or AI context. If you've ever asked a colleague to "send me what you see in the console" or "paste the HTML of that element," you need this. Without it, getting a reliable, one-command snapshot of the live browser is much harder.
Entry point: browsermonitor (global CLI). Run it in any project directory.
.browsermonitor/.puppeteer/screenshot.png (current tab viewport); ideal for LLM vision or quick visual checkscurl (ideal for LLM agents)| Interactive mode | Open mode / Dump output |
|---|---|
 |  |
Install globally from npm:
# Using npm
npm install -g @romanmatena/browsermonitor
# Or pnpm
pnpm add -g @romanmatena/browsermonitor
Note: Chromium download is skipped — browsermonitor uses your system Chrome/Chromium. No extra 300 MB download.
First run (interactive): When you run browsermonitor for the first time in a project directory, interactive mode asks for HTTP API port, saves settings.json, and updates agent files (CLAUDE.md, AGENTS.md, memory.md). When you press o (open), it asks for the default URL.
Re-init: Run browsermonitor init to recreate settings and update agent files.
browsermonitor # Interactive: menu → o (open) or j (join)
browsermonitor --open # Open mode: launch new Chrome and monitor
browsermonitor --join=9222 # Join mode: attach to existing Chrome on port 9222
| Mode | How to run | When to use |
|---|---|---|
| Interactive | browsermonitor (no flags) | First run asks HTTP port. Then menu: o = open Chrome (asks URL on first use), j = join running Chrome, q = quit. |
| Open | browsermonitor --open [url] | Launch a new Chrome and monitor it. Uses current dir for logs. |
| Join | browsermonitor --join=PORT | Attach to an existing Chrome with remote debugging on PORT (e.g. 9222). Port is required. |
When to use: You develop directly on Windows using IIS, XAMPP, or other local server.
cd C:\Projects\my-app
browsermonitor --open https://localhost:5173/
Open mode launches Chrome via Puppeteer. No port proxy or firewall setup needed.
When to use: Your app runs in WSL (Node.js, Python, etc.) but you want Chrome on Windows for GPU/WebGL.
Usage: Run from WSL:
cd /srv/project
browsermonitor --open https://localhost:5173/
How it works: Open mode detects WSL and launches Chrome Canary on Windows, sets up port proxy (0.0.0.0:9222 → Chrome), and connects from WSL via the Windows gateway IP. Port proxy requires Administrator (one-time) on first run.
Join mode (attach to existing Chrome): Start Chrome manually with --remote-debugging-port=9222, then browsermonitor --join=9222 from WSL. For port proxy, run in PowerShell (Admin): netsh interface portproxy add v4tov4 listenport=9222 listenaddress=0.0.0.0 connectport=9222 connectaddress=127.0.0.1
When to use: You develop on native Linux (Ubuntu, etc.) with a display. Chrome/Chromium runs with GUI on the same machine.
browsermonitor --open https://localhost:5173/
Chrome/Chromium is started via Puppeteer with --remote-debugging-port. No port proxy needed; direct localhost connection.
Requirements:
apt install chromium-browser or install Google ChromeFor join mode (attach to existing Chrome): start Chrome manually with --remote-debugging-port=9222, then browsermonitor --join=9222.
Each project gets its own Chrome profile:
%LOCALAPPDATA%\browsermonitor\{project}_{hash} (Windows path).browsermonitor/.chrome-profile/ in project dirSeparate cookies and logins per project; won't interfere with your regular Chrome.
browsermonitor requires Chrome Canary for launching Chrome (--open and --join when no Chrome is running). Regular Chrome cannot be used because Chrome is a singleton — all instances bind to the first launched process. If your regular Chrome is already open, a new Chrome with --remote-debugging-port would just open a window in the existing process and the debug port would be ignored.
Chrome Canary runs as a completely separate process from regular Chrome (different singleton, different profile directory), so:
Installation:
%LOCALAPPDATA%\Google\Chrome SxS\)Note: If you already have Chrome running with --remote-debugging-port (e.g. started manually), you can connect to it with browsermonitor --join=PORT regardless of whether it's Canary or regular Chrome.
When browsermonitor runs in a project directory, it creates:
<project-root>/
├── .browsermonitor/
│ ├── settings.json # Project config (defaultUrl, httpPort, etc.)
│ ├── browsermonitor.pid # PID file for recovery
│ └── .puppeteer/ # All dump outputs
│ ├── console.log
│ ├── network.log
│ ├── network-log/ # Per-request JSON files
│ ├── cookies/ # Per-domain cookie JSONs
│ ├── dom.html
│ └── screenshot.png
│ └── .chrome-profile/ # Chrome profile (native) or
│ # %LOCALAPPDATA%\browsermonitor\ (WSL)
| Key | Action |
|---|---|
d | Dump logs, cookies, screenshot, and current page HTML to files |
c | Clear in-memory buffer |
s | Show status (buffer counts, URLs) |
p | Pause/resume recording (stop/start collecting) |
t | Switch monitored tab |
h | Full help (incl. LLM instructions and HTTP API) |
k | Kill Chrome and exit [open] / kill Chrome and quit [join] |
q | Quit (Chrome stays open) [open] / disconnect only [join] |
| File | Description |
|---|---|
.browsermonitor/.puppeteer/console.log | Console output |
.browsermonitor/.puppeteer/network.log | Network requests |
.browsermonitor/.puppeteer/network-log/ | Detailed request/response JSON |
.browsermonitor/.puppeteer/cookies/ | Cookies per domain |
.browsermonitor/.puppeteer/dom.html | Current page HTML (JS-modified element tree). LLM: read this for the live DOM structure. |
.browsermonitor/.puppeteer/screenshot.png | Screenshot of the current tab viewport (PNG). Written on each dump. |
All files are written on dump (key d or curl …/dump).
Use curl to communicate with the HTTP API over REST. Default URL: http://localhost:60001.
| Endpoint | Description |
|---|---|
GET /dump | Dump logs, DOM, cookies, screenshot to files; returns output file paths |
GET /status | Current state: status, mode, monitored URLs, collecting flag, stats |
GET /stop | Pause collecting (console/network) |
GET /start | Resume collecting |
GET /clear | Clear in-memory buffers |
GET /tabs | List all user tabs (index, url) |
GET /tab?index=N | Switch monitored tab (1-based index) |
GET /computed-styles?selector=... | Get computed CSS for first element matching selector (default: body) |
POST /puppeteer | Call Puppeteer page method. Body: { "method": "page.goto", "args": ["https://..."] } |
Puppeteer whitelist: content, click, focus, goto, hover, pdf, screenshot, select, setDefaultNavigationTimeout, setDefaultTimeout, setViewport, title, type, url, waitForSelector, waitForTimeout
curl http://localhost:60001/dump # Dump to files
curl http://localhost:60001/status # Check status
curl http://localhost:60001/clear # Clear buffers
curl http://localhost:60001/tabs # List tabs
curl "http://localhost:60001/tab?index=2" # Switch to tab 2
curl "http://localhost:60001/computed-styles?selector=.my-class" # Get computed CSS
curl -X POST http://localhost:60001/puppeteer -H "Content-Type: application/json" \
-d '{"method":"page.goto","args":["https://example.com"]}' # Navigate via API
| Option | Description |
|---|---|
--open | Go directly to open mode (launch new Chrome) |
--join=PORT | Go directly to join mode; attach to Chrome at PORT (port required) |
--port=PORT | HTTP API port (default: from settings or 60001) |
--headless | Run Chrome without GUI |
--realtime | Write logs immediately (default: lazy buffer) |
--timeout=MS | Hard timeout in ms; process exits after (0 = disabled) |
--nav-timeout=MS | Navigation timeout in ms (default: from settings, 0 = no limit) |
Config (.browsermonitor/settings.json): defaultUrl, headless, navigationTimeout, ignorePatterns, httpPort, realtime
Verify Chrome is listening:
netstat -ano | findstr "127.0.0.1:9222.*LISTEN"
Verify port proxy:
netsh interface portproxy show v4tov4 | findstr 9222
Should show: 0.0.0.0 9222 127.0.0.1 9222
Test from WSL:
curl -s http://$(ip route | grep default | awk '{print $3}'):9222/json/version
Port proxy blocks port 9222 during Chrome startup. Open mode handles this automatically; if it fails, run PowerShell as Administrator so the port proxy can be configured.
# 1. Remove port proxy (both types)
netsh interface portproxy delete v4tov4 listenport=9222 listenaddress=0.0.0.0
netsh interface portproxy delete v4tov6 listenport=9222 listenaddress=0.0.0.0
# 2. Kill ONLY browsermonitor Chrome (NOT your regular browser!)
Get-WmiObject Win32_Process -Filter "name='chrome.exe'" | Where-Object { $_.CommandLine -match 'browsermonitor' } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }
# 3. Start Chrome Canary (recommended - isolated from regular Chrome)
Start-Process "$env:LOCALAPPDATA\Google\Chrome SxS\Application\chrome.exe" -ArgumentList "--remote-debugging-port=9222","--user-data-dir=$env:LOCALAPPDATA\browsermonitor\manual"
# 4. Wait 5s, check binding, add appropriate proxy
Start-Sleep 5
# Check if IPv4 or IPv6:
netstat -ano | findstr "9222.*LISTEN"
# If 127.0.0.1:9222:
netsh interface portproxy add v4tov4 listenport=9222 listenaddress=0.0.0.0 connectport=9222 connectaddress=127.0.0.1
# If [::1]:9222:
netsh interface portproxy add v4tov6 listenport=9222 listenaddress=0.0.0.0 connectport=9222 connectaddress=::1
WARNING: Never use Stop-Process -Name chrome -Force - it kills ALL Chrome including your personal browser!
This section documents the technical details of connecting to Chrome from WSL2 when Chrome runs on Windows.
WSL2 runs in a lightweight Hyper-V virtual machine with its own network stack:
┌─────────────────────────────────────────────────────────┐
│ Windows Host │
│ Chrome: 127.0.0.1:9222 (localhost only by default) │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ WSL2 VM (e.g., 172.29.100.50) │ │
│ │ │ │
│ │ browsermonitor trying to connect... │ │
│ │ → 127.0.0.1:9222 ❌ (WSL's own localhost) │ │
│ │ → 172.29.96.1:9222 ✅ (Windows gateway) │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
Key insight: localhost in WSL2 refers to WSL's own network, not Windows. To reach Windows services, WSL must connect via the Windows gateway IP (typically 172.x.x.1).
Chrome uses a singleton pattern - only one instance runs per user profile:
First launch: chrome.exe --remote-debugging-port=9222 --user-data-dir=X
→ Starts Chrome, listens on port 9222 ✅
Second launch: chrome.exe --remote-debugging-port=9223 --user-data-dir=Y
→ If Chrome is already running, the new process:
1. Sends command to existing Chrome via IPC
2. Opens new window in EXISTING process
3. New process exits immediately
4. --remote-debugging-port=9223 is IGNORED! ❌
Consequence: If user has Chrome open for regular browsing, launching a new Chrome with debug flags does nothing - the existing Chrome (without debugging) handles it.
Detection method (used in open-mode.mjs):
# From WSL, query Windows WMI for Chrome processes:
wmic.exe process where "name='chrome.exe'" get processid,commandline
# Parse output to find --remote-debugging-port=XXXX
# Multiple subprocesses report same port - deduplicate with Set
Important: Chrome M113+ Security Change
Since Chrome M113 (May 2023), Chrome ignores the --remote-debugging-address=0.0.0.0 flag for security reasons. Chrome always binds to 127.0.0.1 only.
Sources:
| Flag | Binding | Accessible from |
|---|---|---|
--remote-debugging-port=9222 | 127.0.0.1:9222 | Windows localhost only |
--remote-debugging-port=9222 --remote-debugging-address=0.0.0.0 | 127.0.0.1:9222 | IGNORED since Chrome M113 |
For WSL access, port proxy is REQUIRED - there is no way to make Chrome bind to 0.0.0.0.
Windows netsh port proxy forwards connections from one address to another.
IPv4 vs IPv6 Binding:
Chrome may bind to either IPv4 (127.0.0.1) or IPv6 ([::1]) depending on system configuration. The monitor automatically detects which address Chrome uses and configures the appropriate proxy type:
| Chrome Binds To | Proxy Type | Command |
|---|---|---|
127.0.0.1:9222 | v4tov4 | netsh interface portproxy add v4tov4 ... connectaddress=127.0.0.1 |
[::1]:9222 | v4tov6 | netsh interface portproxy add v4tov6 ... connectaddress=::1 |
Detection logic (used in open mode):
// Check netstat output for Chrome's binding
const netstatOutput = execSync('netstat.exe -ano', { encoding: 'utf8' });
const lines = netstatOutput.split('\n').filter(l => l.includes(':9222') && l.includes('LISTEN'));
// Parse for 127.0.0.1:9222 or [::1]:9222
Manual proxy commands:
# IPv4 proxy: forward 0.0.0.0:9222 → 127.0.0.1:9222
netsh interface portproxy add v4tov4 listenport=9222 listenaddress=0.0.0.0 connectport=9222 connectaddress=127.0.0.1
# IPv6 proxy: forward 0.0.0.0:9222 → [::1]:9222
netsh interface portproxy add v4tov6 listenport=9222 listenaddress=0.0.0.0 connectport=9222 connectaddress=::1
# List existing proxies (check both types!)
netsh interface portproxy show v4tov4
netsh interface portproxy show v4tov6
# Remove proxy
netsh interface portproxy delete v4tov4 listenport=9222 listenaddress=0.0.0.0
netsh interface portproxy delete v4tov6 listenport=9222 listenaddress=0.0.0.0
How it works:
WSL (172.29.100.50) → Windows gateway (172.29.96.1:9222)
↓ port proxy (v4tov4 or v4tov6)
Windows (127.0.0.1:9222 or [::1]:9222)
↓
Chrome DevTools Protocol
Important: Port proxy requires Administrator privileges to configure.
Inbound connections to port 9222 require a firewall rule that allows WSL subnet:
# Check existing rules
Get-NetFirewallRule -DisplayName "*Chrome*" | Get-NetFirewallPortFilter
# Add rule with WSL subnet (one-time, persists across reboots)
# 172.16.0.0/12 covers the WSL2 dynamic IP range
New-NetFirewallRule -DisplayName "Chrome Debug (browsermonitor)" -Direction Inbound -LocalPort 9222-9299 -Protocol TCP -Action Allow -RemoteAddress LocalSubnet,172.16.0.0/12
# Update existing rule if it doesn't include WSL subnet
Set-NetFirewallRule -DisplayName "Chrome Remote Debugging" -RemoteAddress LocalSubnet,172.16.0.0/12
Note: If firewall rule exists but connections still timeout, check that RemoteAddress includes the WSL subnet (172.x.x.x range).
The runWslDiagnostics() function performs:
| Step | Check | Method |
|---|---|---|
| 1 | Chrome instances on Windows | wmic.exe process where "name='chrome.exe'" |
| 2 | Network bindings | netstat.exe -ano | findstr 9222 |
| 3 | Port configuration | Parse --remote-debugging-port (note: --remote-debugging-address is ignored since Chrome M113) |
| 4 | Windows Firewall | netsh.exe advfirewall firewall show rule name=all |
| 5 | Port proxy config | netsh.exe interface portproxy show v4tov4 |
| 6 | Scan port range | Check 9222-9299 for existing proxies |
| 7 | Connectivity test | fetch('http://gateway:port/json/version') |
┌──────────────────────────────────────────────────────────────┐
│ browsermonitor --join=9222 │
└──────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────┐
│ Detect Windows gateway IP │
│ (ip route | grep default) │
└───────────────────────────────┘
│
▼
┌───────────────────────────────┐
│ Try connect to gateway:9222 │
└───────────────────────────────┘
│
┌─────────┴─────────┐
│ │
Success Fail
│ │
▼ ▼
┌───────────┐ ┌───────────────────┐
│ Connected │ │ Run diagnostics │
└───────────┘ └───────────────────┘
│
▼
┌───────────────────┐
│ Chrome running │
│ with debug port? │
└───────────────────┘
│
┌─────────┴─────────┐
│ │
Yes No
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Offer port proxy │ │ Show how to │
│ setup (admin) │ │ start Chrome │
└──────────────────┘ └──────────────────┘
| Symptom | Cause | Solution |
|---|---|---|
| Connection refused | Chrome binds to 127.0.0.1 only | Set up port proxy |
| Connection timeout | Chrome binds to IPv6 ([::1]) but proxy forwards to IPv4 | Use v4tov6 proxy instead of v4tov4 |
| New Chrome ignores debug flags | Singleton joined existing process | Close all Chrome windows first, or use port proxy to existing debug port |
| Port proxy won't start | Chrome already listening on 0.0.0.0 | Remove proxy, start Chrome, re-add proxy |
| "Access denied" from WSL | Firewall blocking | Add inbound rule for port 9222 |
IPv6 Troubleshooting:
If connection times out after Chrome starts, check what address Chrome is listening on:
# Check Chrome's binding
netstat -ano | findstr "9222.*LISTEN"
# If you see [::1]:9222 (IPv6), you need v4tov6 proxy:
netsh interface portproxy delete v4tov4 listenport=9222 listenaddress=0.0.0.0
netsh interface portproxy add v4tov6 listenport=9222 listenaddress=0.0.0.0 connectport=9222 connectaddress=::1
# If you see 127.0.0.1:9222 (IPv4), use v4tov4 proxy:
netsh interface portproxy add v4tov4 listenport=9222 listenaddress=0.0.0.0 connectport=9222 connectaddress=127.0.0.1
The monitor detects WSL environment via:
const isWsl = process.platform === 'linux' &&
(process.env.WSL_DISTRO_NAME ||
fs.existsSync('/proc/sys/fs/binfmt_misc/WSLInterop'));
# From WSL: Get Windows gateway IP
ip route | grep default | awk '{print $3}'
# Result: 172.29.96.1
# From WSL: Test Chrome DevTools endpoint
curl -s http://172.29.96.1:9222/json/version | jq
# From WSL: Query Windows processes
wmic.exe process where "name='chrome.exe'" get processid,commandline
# From WSL: Check Windows netstat
netstat.exe -ano | grep 9222
# From Windows: Check what's listening
netstat -ano | findstr "9222.*LISTEN"
runWslDiagnostics(), scanChromeInstances(), Chrome launch and port proxy helpersstartChromeOnWindows(), port proxy, profile pathFAQs
Browser console, network, DOM monitoring for debugging and LLM workflows. Captures console, network, cookies, screenshot, DOM. HTTP API for LLM/scripts. WSL+Windows, Linux, Open/Join modes.
The npm package @romanmatena/browsermonitor receives a total of 5 weekly downloads. As such, @romanmatena/browsermonitor popularity was classified as not popular.
We found that @romanmatena/browsermonitor demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A critical vm2 sandbox escape can allow untrusted JavaScript to break isolation and execute commands on the host Node.js process.
Research
Five malicious NuGet packages impersonate Chinese .NET libraries to deploy a stealer targeting browser credentials, crypto wallets, SSH keys, and local files.
Security News
pnpm 11 turns on a 1-day Minimum Release Age and blocks exotic subdeps by default, adding safeguards against fast-moving supply chain attacks.