peek

peek — local browser-session inspection

Peek is an OSS browser companion for AI coding agents. A Chrome MV3 extension records masked rrweb sessions to a local SQLite store (~/.peek/sessions.db); a stdio MCP server exposes 18 tools that let you inspect those sessions and (with consent) drive the live browser.

Peek itself uploads nothing — no telemetry, no cloud, no account; what your MCP client does with the session data peek returns is up to you. If ~/.peek/sessions.db is absent, peek isn't installed yet — direct the user to npx @peekdev/cli init and stop.

When to invoke

Reach for peek when the user mentions any of these:

• "what happened in my last session" / "show me my recent sessions"
• "investigate this error" alongside a manual repro they just performed
• "what was the user doing when X failed" / "what action triggered X"
• "what did the DOM look like when Y happened"
• "turn what I just did into a Playwright test"
• "click the foo button on this page" (write tools, with consent)
• "fill in this form on the page open in my browser" (write tools, with consent)

Don't reach for peek when:

• The user is asking about production / remote / non-local data
• A test-runner integration is already in scope — use @tracelane/wdio (or the upcoming @tracelane/playwright-reporter) for test-failure capture instead
• The user wants live page introspection at the current moment with no prior recording — peek is for replaying what was already captured, not a live debugger
• The question is about static code, not runtime behavior

The 18 tools

Session-forensics read tools (9) — usable at permission Level 1 (Read-only) and above:

Tool	When
list_recent_sessions	Always the first call. Returns [{ sessionId, origin, startedAt, endedAt, eventCount, ... }] for the last N sessions.
search_sessions	Find sessions by text in title/URL/origin plus facets (origin, date range, status, console/network errors); read-only, returns the same rows as list_recent_sessions. Use when the user says "find the session where..." or wants to narrow down by origin or date.
get_session_summary	Narrative summary of one session — what the user did, top-level errors, key navigations. Start here after list_recent_sessions picks the target.
get_session_console_errors	All console.error / uncaught exceptions in the session, with timestamps.
get_session_network_errors	All ≥ 400 responses, with request URL, method, status, and (where deep-capture was enabled) redacted body.
get_user_action_before_error	Walks rrweb input events backward from a given timestamp; returns the last meaningful user action (click target, form input, navigation). Use right after spotting a console/network error.
get_dom_snapshot	Returns the DOM at a given timestamp as a serialized tree. Use to understand what was on screen when something happened.
query_dom_history	Given a CSS selector + sessionId, returns every snapshot where that element changed. Good for "when did this element appear/disappear/change text".
generate_playwright_repro	Turns a session (or a slice of one) into a runnable Playwright test stub. Selectors are best-effort from rrweb metadata; surface to the user for review before assuming they'll work.