Flutter Lamp

Connect to a running Flutter app's Dart VM Service and start collecting runtime data (logs, exceptions, frames, network). Pass the ws:// or http:// URI printed by `flutter run` (line: 'A Dart VM Service ... is available at:'). NOT purely read-only: enables dart:io HTTP timeline logging on the app so network capture works, and adds the GC stream to the VM timeline recorder so garbage-collection pauses can be correlated with jank. Existing recorded streams are preserved, never replaced.

Why the app is janky, not just how much. Returns frame percentiles, the build-vs-raster split, and findings correlating jank against in-flight requests, route transitions and heap growth — each with its own evidence ids, strength and fix. Reports 'healthy' when jank is within normal range and 'unknown' when there are too few frames to tell a pattern from noise. States what it cannot see: no CPU sampling, no widget rebuild counts. GC pauses are captured and correlated, but the strength of that correlation is reported against how much of the window frames actually covered.

Correlate captured runtime evidence into a root-cause diagnosis. Returns status (diagnosed|unknown), summary, rootCause, evidence (each with a citable eventId), a chronological timeline around the root cause, alternativeCauses that also fit, limitations describing what could not be seen, confidence (0-1) with a breakdown of evidence strength / data completeness / alternative strength, and recommended fixes. Status is 'unknown' below 70% rather than a guess.

Report Android device transports and recommend one, preferring wireless. A `flutter run` started on a USB transport loses its VM Service tunnel when the cable moves; one started on a TCP transport does not. Read-only by default. With promote:true it runs `adb tcpip` and `adb connect` to put a USB-attached device on a TCP transport — that restarts adbd on the device, needs the cable once, and is reversible with `adb usb`. Android-only: reports adbAvailable:false and changes nothing on iOS, desktop or web targets.

Why diagnose_runtime reached its conclusion: the claim, every cited event resolved back to its full record, the timeline around the root cause, competing explanations, what evidence is missing, and the confidence breakdown. Use to answer 'why do you think that' without inventing reasoning.

The whole session as one versioned JSON artifact: metadata, per-collector health, retention, the captured events, and every diagnosis (runtime, performance, navigation, rebuilds). Use mode 'brief' for the smallest sufficient context — the diagnoses plus only the events their evidence cites — and 'full' to archive everything retained, for a bug report, offline analysis or a regression fixture. Sizes are not close: measured on a ~1,700-event session, 'brief' returned 36kB and 'full' returned 247kB — roughly 62,000 tokens, about a third of a 200k context window, so treat 'full' as something to write to a file rather than read inline. Credentials are already redacted at capture, so nothing here was ever stored raw.

Machine-readable capability report: active collectors, every tool with its safety class, what can and cannot be observed on this target, and the current redaction, dashboard and retention configuration. Read this before attempting an operation that may not be supported.

Return the URL of the live Realtime Runtime Dashboard (a browser UI streaming logs, network, exceptions, frames & memory). Open it in a browser to watch the app alongside the AI.

Flutter framework errors and unhandled VM exceptions, most recent first. Each includes the error summary, offending widget, library, and a reconstructed stack trace (data.stackTrace) when available.

Frame build/raster timings. Set onlyJanky to focus on frames over the frame budget — 16.67ms (60fps) by default, which is an assumption: the VM Service does not report the display refresh rate. Override with FLUTTER_LAMP_FRAME_BUDGET_MS when the target's rate is known.

Console output (Stdout/Stderr) and dart:developer logging, most recent first.

Current Dart heap usage for the main isolate (Dart heap in use, capacity, and external/native memory), in MB. Also records a snapshot into runtime history.

The current route and recent route transitions, each with how long it was on screen and the exceptions, failed requests and janky frames attributed to it. Use to answer 'which screen is broken' and to scope other evidence to a screen. Network is attributed by overlap, so a request spanning a route change counts for both.

HTTP requests/responses captured via dart:io profiling (covers Dio & package:http). Fetches the latest profile on demand, then returns completed requests most recent first.

Which widgets are rebuilding and how often, resolved to widget name, file and line, with your own code ranked above package code. Use for 'why is this screen slow to build' and to find needless rebuilds. Requires a debug build with widget creation tracking; reports why it is empty otherwise.

The widget currently selected in the Flutter Inspector (via 'select widget mode' in the app/DevTools). Returns null if nothing is selected.

How much state-management activity the app is doing and when, plus how often build-heavy frames coincide with it — use with get_rebuilds to answer 'is this rebuild storm driven by state churn'. Counts and timing only: Riverpod sends an app-side buffer offset and provider an element id, neither resolvable to a provider name or value. Counts are NOT transition counts — a provider event means dependents were notified, so one state change in a widget-heavy tree produces many events. Stock Bloc posts nothing itself; a flutter_bloc app appears here only as the provider activity its notifications cause.

Recent VM timeline trace events (build/paint/layout/GC/etc.), most recent first. Requires timeline recording — enable with recordFrom=true (sets Dart, GC, Compiler & Embedder streams) then reproduce the activity. recordFrom=true is NOT read-only: it changes the VM's recording configuration. Check recorderLagMs/stalled in the result: the VM recorder can stall permanently once its buffer fills while still reporting its streams as recorded, so events may be historical rather than current.

Snapshot of the running app's widget tree (summary tree from the Flutter Inspector). Use to understand structure, find a widget, or see what is mounted.

One compact answer to 'is this app healthy right now'. Returns a verdict (healthy/degraded/failing/no-data) plus exception, network, frame, log and memory summaries with citable event ids, the retention window, and notes about anything that qualifies the numbers. Call this FIRST instead of calling six get_* tools.

Report connection health, the current debugging session, reconnection state, how many runtime events have been captured by category, and the retention window (per-category capacity, how many events were evicted, and the oldest event still held). Use to confirm the MCP is receiving live data and to know how far back the evidence goes.

Evidence from the window leading up to a failure, plus a baseline comparison: the incident window measured against the equal window before it, per dimension (exceptions, network volume/failures/latency p50/p95, jank ratio, log errors, memory) with directions new/spiked/increased/decreased and citable evidence. Anchors on the given eventId, or the most recent exception, or the current time. Network uses interval matching, so a request that started before the window but failed inside it still counts. When the baseline predates observation, directions are unknown rather than fabricated.