Live browser debugging for AI assistants — DOM, console, network via MCP.
Live browser debugging for AI assistants with DOM, console, and network inspection.
Captured live from the server via tools/list.
create_session
Create a new sncro session. Returns a session key and secret.
Args:
project_key: The project key from CLAUDE.md (registered at sncro.net)
git_user: The current git username (for guest access control). If
omitted or empty, the call is treated as a guest session — allowed
only when the project owner has "Allow guest access" enabled.
brief: If True, skip the first-run briefing (tool list, tips, mobile
notes) and return a compact response. Pass this on the second and
subsequent create_session calls in the same conversation, once
you already know how to use the tools.
After calling this, tell the user to paste the enable_url in their browser.
Then use the returned session_key and session_secret with all other sncro tools.
If no project key is available: tell the user to go to https://www.sncro.net/projects
to register their project and get a key. It takes 30 seconds — sign in with GitHub,
click "+ Add project", enter the domain, and copy the project key into CLAUDE.md.
Parameters (3)
project_keystringrequired
git_userstring
briefboolean
get_console_logs
Get recent console logs and errors from the browser.
Returns the latest console output and any JavaScript errors,
including unhandled exceptions and promise rejections.
This reads from baseline data that the browser pushes every 5 seconds,
so it works even if the browser tab is in the background. If you get a
"no data" error, the browser hasn't connected yet — call check_session
to diagnose, then retry.
Parameters (2)
keystringrequired
secretstringrequired
query_element
Query a DOM element by CSS selector.
Returns bounding rect, attributes, computed styles, inner text,
and child count. Use this to debug layout, positioning, and
visibility issues.
Requires a connected browser session. If you get BROWSER_NOT_CONNECTED,
call check_session first and wait for "connected" status. If you get
BROWSER_TIMEOUT, the page may be navigating — wait a moment and retry.
Args:
key: The sncro session key
secret: The session secret from create_session
selector: CSS selector (e.g. "#photo-wrap", ".toolbar > button:first-child")
styles: Optional list of CSS properties to read (e.g. ["transform", "width", "display"])
Parameters (4)
keystringrequired
secretstringrequired
selectorstringrequired
stylesany
query_all
Query all matching DOM elements by CSS selector.
Returns a summary of each matching element (tag, id, class,
bounding rect, inner text). Useful for checking lists, grids,
or multiple instances of a component.
Requires a connected browser session. If you get BROWSER_NOT_CONNECTED,
call check_session first and wait for "connected" status.
Args:
key: The sncro session key
secret: The session secret from create_session
selector: CSS selector
limit: Max elements to return (default 20)
Parameters (4)
keystringrequired
secretstringrequired
selectorstringrequired
limitinteger
get_network_log
Get network performance data from the browser.
Returns resource timing entries (URLs, durations, sizes) sorted
by duration (slowest first), plus page navigation timing.
Use this to find slow API calls, large assets, or overall page
load performance.
Requires a connected browser session. If you get BROWSER_NOT_CONNECTED,
call check_session first and wait for "connected" status.
Args:
key: The sncro session key
secret: The session secret from create_session
limit: Max resources to return (default 50)
type: Filter by initiator type (e.g. "fetch", "xmlhttprequest", "img", "script", "css")
Parameters (4)
keystringrequired
secretstringrequired
limitinteger
typeany
get_js_value
Read a JavaScript value from the browser by property path.
Walks a strict property path — NO expression evaluation, NO function
calls, NO arbitrary code. Accepts identifiers, integer indices in
brackets, and double-quoted string keys in brackets.
Use this to read runtime state that isn't visible in the DOM:
- Framework hydration: window.__NEXT_DATA__.props.pageProps
- Redux/Zustand/etc stores (if exposed on window): window.__STORE__._currentState
- Feature flags stashed on globals: window.APP.flags
- Nested config: window["site-config"].features[0]
EXPLORATION MODE: pass mode="keys" to get Object.keys() at the path
instead of the value. Start with path="window" to discover globals,
then drill in. This is how to find exposed state without guessing:
get_js_value(path="window", mode="keys")
-> ["document", "__NEXT_DATA__", "store", ...]
get_js_value(path="window.store", mode="keys")
-> ["_currentState", "subscribe", "dispatch", ...]
get_js_value(path="window.store._currentState")
-> the actual state object
LIMITATIONS (intentional — security):
- Cannot call functions. "store.getState()" fails. Expose the value
as a readable property instead, e.g. window.__STORE__.state.
- No arithmetic, comparisons, or expressions.
- Path must start with an identifier and walk down via dots/brackets.
Responses are cycle-safe, depth-capped, and size-capped. DOM nodes
and React fiber trees are summarized rather than traversed.
Args:
key: Session key
secret: Session secret from create_session
path: Property path, e.g. "window.__NEXT_DATA__.props.pageProps"
or 'window["site-config"].features[0]' or 'window.arr[0].name'
mode: "value" (default) returns the serialized value; "keys" returns Object.keys() at the path
max_depth: Max traversal depth when serializing (default 6, capped at 10)
max_bytes: Max serialized size in bytes (default 20000, capped at 100000)
Returns:
{path, type, value, truncated, size_bytes} in value mode
{path, mode, type, keys} in keys mode
{error: "..."} on bad path / function / failure
Requires a connected browser session and middleware v0.9.6+ (older
middleware works — the relay doesn't care; the browser needs agent.js
from relay.sncro.net which auto-updates).
Parameters (6)
keystringrequired
secretstringrequired
pathstringrequired
modestring
max_depthinteger
max_bytesinteger
get_page_snapshot
Get a high-level snapshot of the current page.
Returns URL, title, viewport dimensions, scroll position,
top-level DOM structure, recent console logs, and recent errors.
Requires a connected browser session. If you get BROWSER_NOT_CONNECTED,
call check_session first and wait for "connected" status.
Parameters (2)
keystringrequired
secretstringrequired
get_screenshot
Capture a real pixel screenshot of the user's tab.
Unlike the DOM/style tools, this returns what the browser actually
painted — true fonts, cross-origin images, shadows, gradients, blend
modes. Use it for design review and visual-fidelity checks the DOM
can't answer.
Requires the user to have ticked "Allow screenshots" on the consent
screen AND to have clicked "Share" on the sncro badge to start the
screen-share (a one-time per-session browser prompt). If you get
SCREENSHOTS_NOT_CONSENTED, ask the user to create a new session with
that box checked. If you get SCREENSHOTS_NOT_STARTED, ask them to click
"Share" on the sncro badge in the page corner.
Args:
key: The sncro session key
secret: The session secret from create_session
max_width: Max image width in px; the frame is scaled down to fit (default 1280)
Parameters (3)
keystringrequired
secretstringrequired
max_widthinteger
check_session
Check the connection status of a sncro session.
Call this after create_session to confirm the browser has connected
before using other tools. If status is "waiting", the user hasn't
enabled sncro yet — remind them to click/paste the enable URL,
wait a few seconds, and call check_session again.
Returns:
status: "not_found" | "waiting" | "connected"
session_age_seconds: how long since the session was created
next_step: what to do based on current status
Parameters (2)
keystringrequired
secretstringrequired
end_session
Explicitly close a sncro session — "Finished With Engines".
Call this when you are done debugging and will not need the sncro tools
again in this conversation. After this returns, all sncro tool calls on
this key will refuse with a SESSION_CLOSED message — that is your signal
to stop trying to use them and not apologise about it.
Use it when:
- The original problem is solved and the conversation has moved on
- The user explicitly says "we're done with sncro for now"
- You're entering a long stretch of work that won't need browser visibility
The session can't be reopened. If you need browser visibility later, ask
the user whether to start a new one with create_session.
Parameters (2)
keystringrequired
secretstringrequired
get_feedback
Read incoming feedback for THIS session's project.
Returns bug reports, feature requests, usability notes, and success
stories that other Claude sessions (or the project owner) have
submitted via report_issue, filtered to this session's project. Lets
Claude review what's coming in without needing the admin dashboard.
Scope is strictly "this session's project" — determined by the
project_key used at create_session time and stored in the session.
You cannot read another project's feedback with this tool.
Args:
key: Session key
secret: Session secret from create_session
category: Optional filter — "bug", "feature_request", "usability",
"documentation", or "success_story". Empty = all categories.
limit: Max rows to return (default 20, capped at 100).
Returns:
{project_key, count, feedback: [{id, category, description,
git_user, created_at, shipped_in_build, published}, ...]}
or {error: "..."} on bad auth / missing project.
Parameters (4)
keystringrequired
secretstringrequired
categorystring
limitinteger
report_issue
Report an issue, feature request, or success story for sncro.
IMPORTANT: ALWAYS ask the user before submitting ANY feedback.
Show them exactly what you plan to send and get explicit approval.
Never submit feedback without the user's knowledge and consent.
For ALL categories:
- Draft the text and show it to the user BEFORE submitting
- Wait for explicit approval — do NOT submit until they confirm
- Keep descriptions GENERAL — no proprietary code, no internal
project names, no sensitive data
For SUCCESS STORIES (category: success_story):
- These WILL be displayed publicly on sncro.net
- Ask: "Mind if I share that as a sncro success story?"
- Focus on what sncro did, not what the project is
Args:
project_key: The project key from CLAUDE.md
category: One of: bug, feature_request, usability, documentation, success_story
description: Clear description of the issue, suggestion, or success story
git_user: Your git username
Open-source components of sncro — the MCP relay, the browser-side agent, and the framework plugins that let AI coding assistants inspect a live browser.
What this repo contains
Path
What
relay/
FastAPI app that exposes an MCP server plus long-poll endpoints for agent.js
relay/static/agent.js
Browser-side script injected by the middleware; pushes console + DOM data to the relay
middleware/sncro_middleware.py
FastAPI / Starlette plugin — drop-in middleware for FastAPI apps
middleware/sncro_flask.py
Flask plugin — drop-in middleware for Flask apps
trysncro/
try.sncro.net — a deliberately-broken demo app for exercising sncro end-to-end
How it works
code
┌──────────────┐ MCP ┌──────────┐ long-poll ┌─────────────┐
│ Claude Code │──tools────▶│ relay │◀──────────────│ agent.js │
│ (or other │ │ (relay/) │ snapshots │ (injected │
│ MCP client) │◀──results──│ │──────────────▶│ by plugin) │
└──────────────┘ └──────────┘ └─────────────┘
▲
│ same-origin
│ cookies
┌─────────────┐
│ your app │
│ (plugin is │
│ installed) │
└─────────────┘
Claude calls create_session (MCP tool) → relay returns a 9-digit session key + URL
User visits the URL in the browser where their app is running → confirms via "Allow sncro debugging?"
The plugin drops a cookie, agent.js is injected into subsequent HTML responses on that origin
agent.js pushes baseline data (console, errors) and long-polls for on-demand queries (query_element, get_page_snapshot, etc.)
Using sncro
Most users don't need to run the relay yourself — the hosted version at relay.sncro.net is free-tier friendly. Register your project at sncro.net and grab your project key.
from sncro_flask import init_sncro
app = Flask(__name__)
if app.debug:
init_sncro(app, relay_url="https://relay.sncro.net")
Both middlewares only activate in debug mode — zero overhead in production.
Contributing
We love new framework plugins. CONTRIBUTING.md has the full spec for what a plugin must do — cookies, routes, security headers — plus the test template. Django, Rails, Express, Next.js, ASP.NET, Go — all welcome.
