domstat

Turn a running browser into a low‑entropy, queryable state machine.

domstat is a tiny CLI that lets AI agents and developers query the actual runtime state of a front‑end page (DOM, console, network) without screenshots, DevTools dumps, or high token overhead.

It is designed for fast feedback loops during local development, especially when an AI is writing front‑end code and needs to self‑verify.

Installation

npm install -g @soonit/domstat

Quick Start

1. Launch Chrome with Remote Debugging

domstat launch

Or start Chrome manually:

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir=%TEMP%\chrome-debug

2. Check Connection

domstat ping

3. Query the DOM

domstat query ".nav-bar > span"

Usage

domstat <command> [options]

Commands:
  launch              Launch Chrome with remote debugging enabled
  ping                Check if Chrome CDP is reachable
  query <selector>    Query DOM elements matching the CSS selector

Options:
  --port <number>     Chrome debugging port (default: 9222)
  --host <string>     Chrome debugging host (default: localhost)
  --help              Show help message
  --version           Show version

Why domstat exists

Modern AI coding workflows break down on the front end because feedback is:

• Slow (human inspection)
• Noisy (screenshots, full DOM, DevTools protocol)
• Expensive (large context → high token cost)

domstat solves this by exposing only stable, low‑entropy facts:

• Does an element exist?
• Is it visible?
• What text does it render?
• Are there runtime errors?

No UI interpretation. No automation flows. Just facts.

Core idea

The browser is not a UI. It is a state database.

Humans look at pixels. AI should assert state.

domstat turns a live browser session into something you can query and assert against — cheaply and repeatedly.

What domstat is (and is not)

It is:

• A read‑only browser state inspector
• Optimized for AI self‑testing
• Deterministic and scriptable
• Extremely low token overhead

It is not:

• A test runner
• A Playwright / Puppeteer replacement
• A DevTools wrapper
• A UI automation tool

Example usage

Launch Chrome and check connection:

$ domstat launch
Chrome launched with remote-debugging-port 9222

$ domstat ping
{
  "connected": true,
  "url": "http://localhost:3000/",
  "title": "My App"
}

Query DOM state (jQuery‑like):

$ domstat query ".nav-bar > span"
{
  "exists": true,
  "count": 1,
  "text": "Dashboard",
  "visible": true
}

These outputs are intentionally short, stable, and machine‑friendly.

Typical workflow

AI writes code
↓
devServer hot reloads
↓
domstat queries runtime state
↓
AI fixes code based on facts

This loop is fast enough to run multiple times per minute.

AI Skill

Copy this to your AI assistant's prompt to enable browser state verification:

## Browser State Verification with domstat

You have access to `domstat` - a CLI tool that queries the actual runtime state of the browser via Chrome DevTools Protocol.

### Setup (one-time)

Before querying, ensure Chrome is running with remote debugging:

```bash
domstat launch
```

### Commands

```bash
# Check connection
domstat ping

# Query DOM elements
domstat query "<css-selector>"
```

### Query Response Format

```json
{
  "exists": true,      // Element(s) found
  "count": 1,          // Number of matches
  "text": "Dashboard", // First element's textContent
  "visible": true      // First element's visibility
}
```

### When to Use

After modifying front-end code and the dev server hot reloads, use `domstat query` to verify:

- Element exists: `domstat query "#submit-btn"` → check `exists: true`
- Text content: `domstat query ".error-message"` → check `text` field
- Visibility: `domstat query ".modal"` → check `visible` field
- Element count: `domstat query "li.item"` → check `count` field

### Workflow

1. Write/modify front-end code
2. Wait for hot reload
3. Run `domstat query "<selector>"` to verify changes
4. If verification fails, fix the code and repeat

### Best Practices

- Use specific selectors (IDs, unique classes) for reliable results
- Query after state changes (clicks, form submissions) to verify outcomes
- Check `exists: false` to confirm elements are properly removed
- Use `visible` to verify show/hide logic works correctly

License

MIT