DevWatch

Browser automation tool for Cursor AI to inspect and debug hot-reload development websites.

Requirements

• macOS (for clipboard/paste features)
• Cursor AI (primary use case)
• Node.js 18+
• Yarn (preferred package manager)

Two-Part Architecture

1. DevWatch Server - Headless browser with HTTP API
2. DevWatch CLI (dw) - Terminal client for fast interactions

┌─────────────────┐    HTTP API    ┌──────────────────────┐
│   dw (client)   │ ◄────────────► │  DevWatch Server     │
│ • Screenshots   │                │ • Playwright browser │
│ • Error capture │                │ • Persistent state   │
│ • Zero deps     │                │ • API endpoints      │
└─────────────────┘                └──────────────────────┘

---

Quick Start

1. Start the Server

npm i
npm run setup
npm start

2. Use the CLI

# Install/update CLI
./deployToBin.sh

# Quick status check
dw check

# Take a screenshot
dw screenshot

Server Environment Variables

• PORT - Server port (default: 8787)
• TARGET_URL - Target webpage to control (default: http://localhost:5173)
• BROWSER - Browser to use: firefox, chromium, webkit (default: firefox)

---

CLI Reference (Copy-Paste Ready)

For easy access in Cursor, run dw help-ai or copy this reference:

# DevWatch CLI Commands

Available DevWatch commands for browser automation and debugging:

## Quick Status
- `dw check` - Quick status check (HMR-aware, exits on first error)
- `dw fast-check` - ⚡ Ultra-fast status check (< 1 second, optimized)

## Page Control
- `dw state` - Get page state information
- `dw refresh` - Refresh the page
- `dw hard-refresh` - Hard refresh with cache clear
- `dw force-reload` - Force reload for fresh module loading
- `dw nuclear-reload` - 🚀 NUCLEAR: Clear ALL caches like Firefox Dev Tools
- `dw navigate <url>` - Navigate to a URL
- `dw sync-url <url>` - Sync headless browser to specific URL

## Screenshots
- `dw screenshot [filename] [delayMs]` - Take viewport screenshot
- `dw fullshot [filename] [delayMs]` - Take full page screenshot
- `dw click-screenshot <selector> [text] [delayMs] [filename] [--clipboard] [--paste]` - Click element and screenshot
  - `--clipboard` copies image to clipboard (macOS)
  - `--paste` auto-pastes into Cursor (requires Accessibility permissions)

## Console Logs
- `dw logs [type] [limit]` - Get console logs (types: error, warn, info, log, debug)
- `dw errors` - Get only error logs
- `dw clear-logs` - Clear console log buffer
- `dw export-logs [filename]` - Export logs to text file

## Page Interaction
- `dw click <selector> [text]` - Click an element
- `dw fill <selector> <value>` - Fill an input field
- `dw type <text> [delay]` - Type text with optional delay
- `dw hover <selector>` - Hover over an element
- `dw scroll [x] [y]` - Scroll the page (default: 0, 500)

## JavaScript Execution
- `dw eval <code>` - Execute JavaScript code in page context

## Debugging
- `dw debug` - Get comprehensive debug information
- `dw match-firefox` - Match Firefox Developer Edition state exactly
- `dw sync-firefox [url]` - EXACT Firefox sync with fresh page instance
- `dw force-modules` - Force all module scripts to load and show errors
- `dw capture-errors` - Proven error capture with fresh page instance

## Examples
```bash
# Quick status check
dw check

# Screenshots
dw screenshot
dw click-screenshot "button" "Submit" --paste  # Click, screenshot, paste to Cursor

# Page interaction
dw click "#login-button"
dw fill "#email" "test@example.com"
dw scroll 0 500

# Debugging
dw errors
dw nuclear-reload  # For stubborn cache issues

Environment: Set DEVWATCH_URL to use different server (default: http://127.0.0.1:8787)

---

## DevWatch CLI (dw)
The CLI lives at `~/bin/dw` and is also checked into this repo as `./dw` for safekeeping.

- Default server URL: `http://127.0.0.1:8787`
- Override with: `export DEVWATCH_URL=http://host:port`

### Installation / update
- Local copy: `./dw`
- Deploy helper: `./deployToBin.sh` copies `./dw` to `~/bin/dw` and makes it executable.
  - Usage:
    ```bash
    ./deployToBin.sh
    ```
  - Ensure `~/bin` is on your PATH.

### Usage
```bash
dw <command> [options]

Quick status

• dw check — Quick status check (HMR-aware, exits non-zero on first error)
• dw fast-check — Ultra-fast status check (< 1s, optimized)

Page control

• dw state — Get page state information
• dw refresh — Refresh the page
• dw hard-refresh — Hard refresh with cache clear (slower)
• dw force-reload — Force reload for fresh module loading (slower)
• dw nuclear-reload — NUCLEAR: Clear ALL caches like Firefox Dev Tools
• dw navigate <url> — Navigate to a URL
• dw sync-url <url> — Sync headless browser to a specific URL

Screenshots

• dw screenshot [filename] [delayMs] — Viewport screenshot
  • You can also pass the delay first: dw screenshot 1500 my.png
• dw fullshot [filename] [delayMs] — Full page screenshot
  • Same flexible args order as screenshot
• dw click-screenshot <selector> [text] [delayMs] [filename] [--clipboard] [--paste]
  • Clicks an element (optionally filtering by inner text), waits delay, then screenshots
  • If --clipboard is provided, the image is copied to the clipboard (macOS AppleScript)
  • If --paste is provided, it will also activate Cursor and paste the image (requires Accessibility permissions)
  • Default delay: 2000ms when unspecified

Examples:

# Viewport screenshot with default name
dw screenshot

# Full page screenshot with filename and delay
dw fullshot page.png 1000

# Delay-first order works too
dw screenshot 1500 shot.png

# Click a Submit button and save/paste screenshot
dw click-screenshot "button" "Submit" 2000 submit.png

# Copy screenshot to clipboard instead of saving to file
dw click-screenshot "#save" --clipboard

# Click, screenshot, copy to clipboard and attempt to auto-paste into Cursor
# (Enable System Settings > Privacy & Security > Accessibility for Terminal)
dw click-screenshot ".result" --paste

Notes on clipboard/paste:

• A temporary file is stored at /tmp/devwatch-screenshot.png during the operation and removed after.
• --paste uses AppleScript to bring Cursor to the foreground and send Cmd+V, then Return.

Console logs

• dw logs [type] [limit] — Get console logs (types: error, warn, info, log, debug)
• dw errors — Get only error logs
• dw clear-logs — Clear console log buffer
• dw export-logs [filename] — Export logs to text file

Page interaction

• dw click <selector> [text] — Click an element
• dw fill <selector> <value> — Fill an input field
• dw type <text> [delay] — Type text with optional delay
• dw hover <selector> — Hover over an element
• dw scroll [x] [y] — Scroll the page (default: 0, 500)

JavaScript

• dw eval <code> — Execute JavaScript code in page context

Debugging

• dw debug — Get comprehensive debug information
• dw match-firefox — Match Firefox Developer Edition state (clear caches and reload)
• dw sync-firefox [url] — EXACT Firefox sync with fresh page instance
• dw force-modules — Force all module scripts to load and show errors
• dw capture-errors — Proven error capture (fresh page with comprehensive capture)

---

HTTP API (server)

These endpoints back the CLI and are available directly for scripted use.

GET /state

Get current page state (title, URL, dimensions)

GET /frame

Get screenshot of current page as PNG

GET /logs?since=timestamp

Get console logs since timestamp

GET /network?since=timestamp

Get network events since timestamp

POST /dom/find

Find DOM elements by selector and optional text

{"selector": "button", "text": "Click me"}

POST /click

Click an element

{"selector": "button", "text": "Submit"}

POST /type

Type text with optional delay

{"text": "Hello world", "delay": 50}

POST /fill

Fill input field

{"selector": "#email", "value": "test@example.com"}

POST /hover

Hover over element

{"selector": ".tooltip-trigger"}

POST /scroll

Scroll page

{"x": 0, "y": 500}

POST /eval

Execute JavaScript in page context

{"js": "return document.title"}

HTTP usage examples

# Get page state
curl http://localhost:8787/state

# Take screenshot
curl http://localhost:8787/frame > screenshot.png

# Click a button
curl -X POST http://localhost:8787/click -H "Content-Type: application/json" \
  -d '{"selector":"button","text":"Submit"}'

# Fill a form
curl -X POST http://localhost:8787/fill -H "Content-Type: application/json" \
  -d '{"selector":"#email","value":"test@example.com"}'

---

Support the Project ☕

If DevWatch saves you time in your development workflow, consider buying me a coffee!

Other ways to support:

• ⭐ Star this repository - Helps others discover the project
• 🐛 Report issues - Help improve the tool
• 🚀 Contribute code - Pull requests welcome!
• 📢 Share with others - Spread the word about DevWatch

Built with ❤️ for developers using AI assistants and hot-reload workflows.