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

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"] }

Related MCP server: cdp-tools-mcp

Runtime Debugging

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

Supported Languages

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

Features

• Passive browser recording — capture network, console, DOM, storage, and screenshots without code changes

• Framework-aware — React and Vue state tracking with bug pattern detection

• Session investigation — search, inspect, diff, and replay recorded browser sessions

• Compact viewport — debugger state rendered in ~400 tokens per stop, optimized for LLM context windows

• Conditional breakpoints — order.py:147 when discount < 0, hit counts, logpoints

• Watch expressions — persistent expressions auto-evaluated on every stop

• Framework detection — auto-detects pytest, Django, Flask, jest, mocha, go test

• Multi-threaded — thread/goroutine listing and selection

• Shell completions — tab-completion for bash, zsh, and fish via krometrail completions

Skill File

Install the agent skill for CLI-based workflows. Install via skilltap or print to stdout:

skilltap install ./skill  # Install via skilltap
krometrail skill            # Or print skill to stdout

Development

bun install              # Install dependencies
bun run dev              # Run CLI in dev mode
bun run mcp              # Run MCP server
bun run build            # Compile single binary
bun run build:all        # Build for all platforms (Linux, macOS, Windows)

Testing

bun run test             # All tests
bun run test:unit        # Unit tests (no external deps)
bun run test:integration # Integration tests (needs debuggers)
bun run test:e2e         # E2E tests (full MCP path)
bun run test:agent       # Agent harness scenarios

Integration and E2E tests require debuggers to be installed. Run krometrail doctor to check availability. Tests skip cleanly per-adapter when a debugger is not found.

Agent Harness

The agent harness (tests/agent-harness/) is a scenario-based test suite for evaluating how well agents debug with Krometrail. It contains 35 scenarios across 3 languages at 5 difficulty levels:

• Python — 12 scenarios (closure bugs, mutation errors, float accumulation, deep pipelines)

• Node.js — 11 scenarios (async races, event loop ordering, regex state, this binding)

• TypeScript — 12 scenarios (type assertion escapes, generic constraints, runtime registries)

bun run test:agent          # Run scenarios
bun run test:agent:report   # Generate report with token/cost metrics

Linting

bun run lint             # Check with Biome
bun run lint:fix         # Auto-fix

Architecture

src/
  mcp/          MCP server + tool handlers
  cli/          CLI entry point + commands (citty)
  core/         Session manager, viewport renderer, DAP client, compression
  adapters/     Language-specific debugger adapters (6 languages)
  browser/      Chrome CDP recording, investigation engine, framework observers
  daemon/       Session persistence over Unix socket
  frameworks/   Auto-detection for test/web frameworks

The MCP server and CLI share the same core. Browser tools use CDP to record events into a SQLite-backed session store with JSONL event storage. Debug tools use the session manager to orchestrate DAP communication. The viewport renderer formats state for agents, and adapters handle language-specific debugger setup.

Documentation

License

MIT