krometrail

Krometrail

Browser observation and runtime debugging for AI coding agents.

curl -fsSL https://krometrail.dev/install.sh | sh

Krometrail is an MCP server and CLI that gives AI coding agents eyes into running applications. It records browser activity — network requests, console output, DOM mutations, framework state, storage changes, and screenshots — then lets agents search, inspect, and diff that recorded session to diagnose bugs. It also bridges the Debug Adapter Protocol (DAP) for breakpoint-level debugging across 6 languages.

Browser Observation

Record everything happening in a browser session and investigate it later — no code changes required.

What Gets Captured

• Network — every request/response with headers, bodies, status codes, timing, and WebSocket frames
• Console — all console output with levels, args, and stack traces
• DOM mutations — meaningful structural changes (forms, dialogs, sections)
• User input — clicks, form submissions, field changes
• Screenshots — periodic and navigation-triggered snapshots
• Browser storage — localStorage/sessionStorage mutations and cross-tab events
• Framework state — React and Vue component lifecycles, state/prop diffs, store mutations
• Framework errors — auto-detected anti-patterns (stale closures, infinite re-renders, missing cleanup)

Quick Start

Add to your agent's MCP config (.mcp.json in your project root):

{
  "mcpServers": {
    "krometrail": {
      "command": "krometrail",
      "args": ["--mcp"]
    }
  }
}

Start recording a browser session:

# MCP: chrome_start({ url: "http://localhost:3000", framework_state: true })
# CLI:
krometrail chrome start http://localhost:3000 --framework-state

# Place markers at significant moments
krometrail chrome mark "submitted form"

# Stop recording
krometrail chrome stop

Investigate what happened:

# List recorded sessions
krometrail session list --has-errors

# Get a structured overview
krometrail session overview <session-id>

# Search for specific events
krometrail session search <session-id> --event-types network_response --status-codes 500
krometrail session search <session-id> --framework react --pattern stale_closure

# Deep-dive into a specific event
krometrail session inspect <session-id> --event-id <id>

# Compare two moments (what changed between page load and error?)
krometrail session diff <session-id> --from <timestamp> --to <timestamp>

# Generate reproduction steps or test scaffolds
krometrail session replay-context <session-id> --format playwright

Browser MCP Tools

Tool	Description
chrome_start	Launch Chrome and start recording (URL, framework observation, tab filtering)
chrome_status	Current recording status, event counts, active tabs
chrome_mark	Place a named marker in the recording timeline
chrome_stop	Stop recording and persist events to database
session_list	List recorded sessions with filters (time, URL, errors, markers)
session_overview	Structured overview: navigation, markers, errors, network, framework summary
session_search	Full-text and structured search across recorded events
session_inspect	Deep-dive into a specific event with full context and nearest screenshot
session_diff	Compare two moments: URL, storage, console, network, framework state changes
session_replay_context	Generate reproduction steps or Playwright/Cypress test scaffolds

Framework State Observation

When enabled, Krometrail hooks into React DevTools and Vue Devtools to track:

• Component mount/update/unmount lifecycles
• State and prop changes with before/after diffs
• Render counts and trigger source identification
• Pinia/Vuex store mutations (Vue)
• Auto-detected bug patterns: stale closures, infinite re-renders, missing effect cleanup, excessive context re-renders

{ "url": "http://localhost:3000", "framework_state": true }
{ "url": "http://localhost:3000", "framework_state": ["react"] }
{ "url": "http://localhost:3000", "framework_state": ["react", "vue"] }

Runtime Debugging

Set breakpoints, step through code, and inspect variables across 6 languages via DAP.

Supported Languages

Language	Debugger	Adapter	Status
Python	debugpy	TCP	Stable
Node.js	js-debug	TCP	Stable
Go	Delve	TCP	Stable
Rust	CodeLLDB	TCP	Stable
Java	java-debug-adapter	TCP	Stable
C/C++	GDB 14+ / lldb-dap	stdio	Stable

Debug CLI

krometrail launch "python app.py" --break order.py:147
krometrail step over
krometrail eval "discount"
krometrail vars --scope local
krometrail continue
krometrail stop

Debug MCP Tools