Query browser runtime state for AI agents via Chrome DevTools Protocol
npm install @soonit/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.
---
``bash`
npm install -g @soonit/domstat
---
`bash`
domstat launch
Or start Chrome manually:
`bashmacOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
--remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
$3
bash
domstat ping
`$3
bash
domstat query ".nav-bar > span"
`---
Usage
domstat [options]Commands:
launch Launch Chrome with remote debugging enabled
ping Check if Chrome CDP is reachable
query Query DOM elements matching the CSS selector
Options:
--port Chrome debugging port (default: 9222)
--host 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)
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)
$3
- A read‑only browser state inspector
- Optimized for AI self‑testing
- Deterministic and scriptable
- Extremely low token overhead
$3
- A test runner
- A Playwright / Puppeteer replacement
- A DevTools wrapper
- A UI automation tool
---
Example usage
Launch Chrome and check connection:
`bash
$ 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):
bash
$ domstat query ".nav-bar > span"
{
"exists": true,
"count": 1,
"text": "Dashboard",
"visible": true
}
`These outputs are intentionally short, stable, and machine‑friendly.
---
Typical workflow
text
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:
markdown
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.$3
Before querying, ensure Chrome is running with remote debugging:
`bash
domstat launch
`$3
bash
Check connection
domstat pingQuery DOM elements
domstat query ""
`$3
json
{
"exists": true, // Element(s) found
"count": 1, // Number of matches
"text": "Dashboard", // First element's textContent
"visible": true // First element's visibility
}
`$3
After modifying front-end code and the dev server hot reloads, use
to verify:- Element exists:
domstat query "#submit-btn" → check exists: true
- Text content: → check text field
- Visibility: domstat query ".modal" → check visible field
- Element count: domstat query "li.item" → check count field$3
1. Write/modify front-end code
2. Wait for hot reload
3. Run
domstat query " to verify changes
4. If verification fails, fix the code and repeat$3
- 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
```---
MIT