I built an open-source tool called Whelmer. It gives AI agents full visibility into what a browser is doing. Every DOM change, every network request, every console message, every storage mutation — nothing is hidden, nothing is filtered.
Here is exactly what it is, why I built it, and how it works.
The Problem
When you connect to a browser debug port, the browser emits events for everything. CDP alone has 53 domains with hundreds of event types. Every DOM change, every network request, every console message, every CSS update, every storage mutation, every security state change — all of it flows out as WebSocket messages.
But existing agent tools give you a filtered view. They show you the events they think you need and drop the rest. You do not see what you do not know exists.
If a page fires a Storage event that reveals how an SPA manages auth tokens, most tools never tell you. If a service worker intercepts a request and modifies the response, most tools never show you. You are working blind.
It gets worse with multi-browser support:
- Firefox uses a completely different protocol (BiDi or FDP)
- Safari uses WebKit Remote Debugging Protocol
- Most tools only support Chrome via CDP
- Agent frameworks that claim multi-browser support often hide protocol differences behind opinionated abstractions that drop events
You end up debugging in the dark.
What Whelmer Does
Whelmer shows you everything.
Every event from every enabled domain flows through an EventBus with a 10,000-event ring buffer. You can stream all events as NDJSON. You can filter by domain. You can replay history. You can enable or disable any of the 53 CDP domains at runtime.
Nothing is hidden. Nothing is filtered. You get the full firehose and decide what matters.
It connects to Chrome, Brave, Edge, Opera, and Firefox out of the box. Four protocols. One binary. Same event model.
Why I Built It
I built Whelmer for a specific job: reverse-engineering the web apps and their internal API. This project was built using Whelmer: https://github.com/Sumama-Jameel/Mirage
When OpenAI, Google, Grok, Qwen, or others update their UI or internal API format, integrations that depend on those internal APIs break. You need to see exactly what changed. You need to see every network request, every console message, every storage mutation as raw JSON.
Whelmer exposes all of that in your terminal. You see exactly what changed and fix your integration in minutes instead of hours. No switching to browser DevTools. No manual inspection. Just raw protocol data.
That project (an OpenAI-compatible API wrapper that routes through these internal APIs — Mirage) is what drove the need for Whelmer.
How It Works
The data flow is a pipeline with four stages:
WsConnection — Persistent WebSocket connection to the browser debug port. Writer task sends commands. Reader task routes responses back to callbacks and all other messages to an mpsc channel.
EventBus — Bridges the mpsc receiver to a broadcast channel and a ring buffer. A bridge task reads every event from the mpsc channel and publishes it to all broadcast subscribers while simultaneously appending it to the in-memory history buffer. No events are dropped.
Display Consumer — Spawned automatically on startup. Handles known event types and prints them formatted to the terminal. One directional: reads from the broadcast channel, writes to stdout.
Agent Consumer — Created on demand when you run the
eventscommand. Subscribes to the broadcast channel for live streaming, or reads from the ring buffer for history. Supports--json,--history N, and domain filtering. Multiple agent consumers can run simultaneously.
The key design choice: the EventBus decouples event production from consumption. The bridge task never blocks. Every consumer gets every event. There is no "you get this, you do not get that" routing logic at the bus level.
Multi-Protocol Support
Whelmer supports four protocols:
- CDP — Chrome DevTools Protocol (Chrome, Brave, Edge, Opera)
- BiDi — WebDriver BiDi Protocol (W3C standard, works in Chrome and Firefox)
- FDP — Firefox DevTools Protocol (older Firefox versions)
- Foxbridge — CDP-to-Firefox proxy
One tool covers every major browser. Add a new protocol by implementing the ProtocolConnection trait.
Commands
Whelmer has a full command set:
-
tabs— List, create, close, activate browser tabs -
attach— Switch to a specific tab -
dom— Inspect the page DOM -
eval— Run JavaScript in page context -
cookies— Read/write/delete cookies -
storage— Inspect or modify localStorage / sessionStorage -
cache— Show Cache Storage data -
indexeddb— Show IndexedDB databases -
network— Live request/response monitoring -
export— Export all data to JSON -
screenshot— Capture page screenshot -
perf— Show performance metrics -
security— Show page security state -
websockets— Show WebSocket connections and frames -
events— Stream raw protocol events -
domains— List all 53 CDP domains -
enable/disable— Toggle CDP domains at runtime -
capture— In-REPL capture session -
records— List / inspect captured requests -
replay— Export captures as HAR, CSV, or JSON -
diff— Compare two captures -
doctor— Run diagnostic battery
Every data command accepts --json for machine-readable output.
Recording and Replay
Whelmer can record browser sessions:
# One-shot capture: record until the target API responds, then stop
whelmer record --until "api/chat" --output caps.ndjson
# Saved session: reuse your filter set anywhere
whelmer record @myapi --duration 60s
# Background daemon: runs detached, writes a .done marker when finished
whelmer record --until "api/chat" --output caps.ndjson --detach
You can replay captures:
# Replay a capture as HAR, CSV, or JSON
whelmer replay caps.ndjson --grep "api/chat" --export har --output chat.har
# Rebuild a single recorded request as a copy-paste cURL command
whelmer curl caps.ndjson chat-abc123
# Compare two captures — finds what the API contract changed
whelmer diff run1.ndjson run2.ndjson --json
This is how you debug when a provider changes their internal API. You record before the change, record after the change, and diff them.
Machine-Readable Control
Whelmer can expose its session over JSONL for agents and automation:
# Expose the session over JSONL on stdin/stdout
whelmer serve
# TCP listener with auto-generated auth token
whelmer serve --tcp 9876
# Unix domain socket (permission-gated, no token needed)
whelmer serve --unix /tmp/w.sock
This lets AI agents control Whelmer programmatically.
Under the Hood
Whelmer is written in pure Rust. No Node.js. No Python. No npm install. No bundler. One static binary, about 7 MB. Runs on any Linux, macOS, or Windows machine with a browser.
The project structure:
src/
├── main.rs # CLI entry point, REPL loop
├── connection.rs # Persistent WebSocket with command/response routing
├── event_bus.rs # Broadcast channel + ring-buffer history
├── events.rs # Event processors + DomainRegistry (53 CDP domains)
├── formatters.rs # Output formatters (JSON, Table, CSV, YAML, Text)
├── handlers.rs # Command handlers (cookies, storage, DOM, eval, etc.)
├── protocol.rs # ProtocolConnection trait + ProtocolEvent enum
├── protocol_detector.rs # Auto-detect browser and protocol on the network
├── record.rs # One-shot record orchestration
├── diagnose.rs # `whelmer doctor` diagnostic battery
├── curl.rs # Record → cURL command reconstruction
├── capabilities.rs # Static per-protocol capability matrices
├── capture/ # Correlation engine, filters, sinks, replay, diff
├── protocols/
│ ├── mod.rs # Protocol implementations
│ ├── cdp.rs # Chrome DevTools Protocol
│ ├── bidi.rs # WebDriver BiDi Protocol
│ ├── fdp.rs # Firefox DevTools Protocol (RDP)
│ └── foxbridge.rs # Foxbridge CDP-to-Firefox proxy
All tests run with mock connections. No browser needed. 379 unit tests, 14 binary tests, 2 integration tests passing.
Privacy by Design
Whelmer connects to your local browser only. No cloud. No telemetry. No data leaves your machine. No accounts. No signup.
You run it against your own browser, on your own machine. That is it.
The Honest Catch
Whelmer gives you the raw firehose. That means you get a lot of noise. If you enable all 53 CDP domains, your terminal will be flooded with events. You need to know which domains matter for your use case.
Also, browser protocols change. Chrome updates CDP. Firefox updates BiDi. When that happens, Whelmer needs updates too. This is not a "set it and forget it" tool. It requires maintenance as browsers evolve.
And because Whelmer shows everything, it is not a beginner tool. If you do not understand what CDP domains are or what a Storage event means, Whelmer will overwhelm you. It is built for people who already understand browser internals and need deeper visibility.
Who It Is For
Whelmer is for:
- AI agent developers who need to debug why their agents fail on complex websites
- Reverse engineers who need to understand how web apps work internally
- Security researchers who need to see every network request and storage mutation
- Anyone building tools that interact with browsers and needs full protocol visibility
It is not for people who just want to scrape a website. It is for people who need to understand the browser at the protocol level.
How to Run It
Whelmer is open source under the MIT license.
Build from source:
git clone https://github.com/Sumama-Jameel/whelmer.git
cd whelmer
cargo build --release
./target/release/whelmer
Or install from crates.io:
cargo install whelmer
whelmer
Then open a browser with remote debugging enabled:
# Chrome / Chromium
google-chrome --remote-debugging-port=9222
# Firefox (BiDi)
firefox --remote-debugging-port=9222
# Brave
brave --remote-debugging-port=9222
Whelmer auto-detects the browser, protocol, and port. Just run it.
GitHub link: https://github.com/Sumama-Jameel/Whelmer
Top comments (0)