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

| Tool | Description | |------|-------------| | debug_launch | Launch a program with initial breakpoints | | debug_attach | Attach to a running process | | debug_stop | Terminate the debug session | | debug_status | Query session state and capabilities | | debug_continue | Resume execution until next breakpoint | | debug_step | Step over, into, or out | | debug_run_to | Run to a specific line | | debug_set_breakpoints | Set breakpoints with conditions, hit counts, logpoints | | debug_set_exception_breakpoints | Filter by exception type | | debug_list_breakpoints | List all active breakpoints | | debug_evaluate | Evaluate an expression in the current frame | | debug_variables | Inspect variables by scope with regex filtering | | debug_stack_trace | Get the full call stack | | debug_source | Read source code around a location | | debug_watch | Add/remove persistent watch expressions | | debug_action_log | Review the investigation log | | debug_output | Capture stdout/stderr | | debug_threads | List threads, goroutines, etc. |

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

| Document | Contents | |----------|----------| | VISION.md | Problem statement, prior art, roadmap | | ARCH.md | System layers, data flow, viewport rendering | | UX.md | Viewport abstraction, agent interaction patterns | | SPEC.md | Adapter contract, type definitions | | INTERFACE.md | MCP tool + CLI command reference | | TESTING.md | Testing philosophy and tiers |

License

MIT