Repository avatar
Other Tools
v1.0.1
active

crumbs

io.github.anilcancakir/crumbs

Read a running Flutter app's HTTP, logs, exceptions, dumps and frames over MCP. Debug builds only.

Documentation

Crumbs logo

Crumbs

Let your AI agent read what your Flutter app just did.
HTTP traffic, logs, uncaught exceptions, debug prints, events, gate checks, DB queries and cache operations, captured in memory while the app runs and read from one CLI and one MCP server. No stack traces pasted into the chat, no proxy, no SaaS account.

pub package CI codecov License: MIT pub points

Documentation · pub.dev · Issues

crumbs is a passive inspector: it records what the app does and drives nothing. Watchers hook package:logging, FlutterError.onError, debugPrint and the frame scheduler, and call any handler set before them; the log watcher also turns on hierarchical logging and sets Logger.root.level to Level.ALL, so every log record reaches the buffer. HTTP adapters and the Magic watchers feed the rest. Every record lands in a ring buffer inside the app, and ext.crumbs.* VM Service extensions serve those buffers to crumbs:* commands and crumbs_* MCP tools on dowel. Its sibling tapir drives the app; crumbs reads what the app captured. crumbs is inspired by Laravel Telescope, which records the requests, exceptions, logs, queries, cache hits and events of a Laravel app into a queryable timeline; crumbs serves the same kind of timeline to a terminal and an AI agent instead of a web dashboard.

At a glance

FactValue
Packagecrumbs
Installflutter pub add crumbs, then dart run crumbs crumbs:install
Importpackage:crumbs/crumbs.dart (CrumbsPlugin.install(), behind if (!kReleaseMode))
Entry pointsdart run crumbs <command>, ./bin/dowel <command>, CrumbsPlugin.install(), CrumbsPlugin.registerWatcher(), CrumbsPlugin.registerHttpAdapter(), CrumbsStore, CrumbsRedaction, CrumbsFileSink, CrumbsDowelProvider (package:crumbs/cli.dart), dart run crumbs mcp:serve
PlatformsAny Flutter target that exposes a VM Service in a debug or profile build: Android, iOS, macOS, Windows, Linux, and web for everything except the file sink: CrumbsFileSink imports dart:io with no conditional import, so the timeline on disk needs a native target and pub.dev shows no Web tag. On a Windows host mcp:install writes a dart run entry, never ./bin/dowel
RequiresDart 3.13, Flutter 3.47; a plugin of dowel (^1.0.0)
Dependenciesdowel, logging, meta, the Flutter SDK
LicenseMIT

Install

flutter pub add crumbs
dart run crumbs crumbs:install
dart run crumbs start --device=macos   # dowel records the session every crumbs:* command dials
dart run crumbs crumbs:tail

crumbs:install scaffolds the dowel harness when bin/dispatcher.dart is missing (including the fast ./bin/dowel launcher), registers crumbs as a dowel plugin, and patches lib/main.dart: the imports, WidgetsFlutterBinding.ensureInitialized() when missing, and an !kReleaseMode block that installs crumbs with the exception and dump watchers, placed before await Magic.init( on a Magic app and before runApp( otherwise. Re-running it changes nothing. Wired by hand, main.dart looks like this:

import 'package:crumbs/crumbs.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter/widgets.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  if (!kReleaseMode) {
    CrumbsPlugin.install();
    CrumbsPlugin.registerWatcher(ExceptionWatcher());
    CrumbsPlugin.registerWatcher(DumpWatcher());
  }
  runApp(const MyApp()); // MyApp is the host app's root widget.
}

The guard belongs to the call site: crumbs installs none of its own. !kReleaseMode is what the installer writes: it keeps crumbs in debug and profile builds, and a frame measurement needs a profile build. A release build tree-shakes crumbs. Without a guard crumbs ships in release, and anyone who reaches that app's VM Service can read every buffer. --dart-define=CRUMBS_DISABLE=1 makes CrumbsPlugin.install(), registerWatcher() and registerHttpAdapter() return without installing anything, in a build that must not expose the extensions. The example/ app wires the core watchers and routes Dio traffic into the HTTP buffer.

On a Magic app, MagicCrumbsIntegration.install() from package:magic_devtools/crumbs.dart, called after Magic.init(), registers the Magic HTTP adapter and the model, cache, event, gate and query watchers. A magic_devtools release built on crumbs ships the Magic integration (package:magic_devtools/crumbs.dart); the installer wires it when the resolved magic_devtools has that library, and otherwise warns and skips the Magic wiring, so Magic's buffers stay empty until you upgrade.

What it captures

RecordCaptured byCLIMCP tool
package:logging recordsLogWatcher, installed by CrumbsPlugin.install()crumbs:tailcrumbs_tail
Uncaught exceptionsExceptionWatcher (FlutterError.onError and PlatformDispatcher.onError, chained to any handler already set, such as Sentry's)nonecrumbs_exceptions
debugPrint outputDumpWatcher (debug builds only unless allowInRelease is set)crumbs:dumpscrumbs_dumps
Frame timings and build attributionFramePerfWatchercrumbs:framescrumbs_frames
HTTP requestsThe app's own interceptor (Dio, package:http) calling CrumbsStore.recordHttp, or a CrumbsHttpAdapter; on Magic, MagicHttpFacadeAdaptercrumbs:requestscrumbs_requests
In-app eventsMagicEventWatchercrumbs:eventscrumbs_events
Gate checksMagicGateWatchercrumbs:gatescrumbs_gates
DB queriesMagicQueryWatchercrumbs:queriescrumbs_queries
Cache operationsMagicCacheWatchercrumbs:cachescrumbs_caches
Model lifecycleMagicModelWatchernone (CrumbsStore.recentModels() in the app)none

crumbs:clear and crumbs_clear empty every buffer, which turns the next read into the output of one action. Each buffer keeps the newest 500 records by default and the frame buffer 3600; CrumbsStore.setCapacity() changes one or all of them. A read returns records oldest first. crumbs:tail and crumbs:events take --since, --json and --follow to stream a buffer from a cursor.

Secrets and the timeline on disk

SurfaceBehaviour
Credential maskingRecords are masked by key before they are buffered, with no setup: Authorization, Cookie, X-Api-Key and similar headers, password, token style keys in a JSON or form request or response body, credential-named parameters in the URL query (access_token, api_key, the X-Amz-* signature of a presigned URL), and the same keys inside the Map elements of a query's bindings and a gate check's arguments, read ******** (a positional binding has no key, so only a text redactor can mask it, and it sees the bare value). Extend the lists with CrumbsRedaction.hideRequestHeaders(), hideRequestParameters() and hideResponseParameters()
Text redactorCrumbsRedaction.redactor, a String Function(String) you set, runs at insert over the free text of a log, event, exception and HTTP record, a dump's message, a query's SQL and bindings, and a gate's arguments and user id. Without one, a credential written into a log line, a debugPrint or a SQL literal is buffered as written; model attributes and cache records are never masked. A redactor that throws drops the record rather than let it through unmasked; the log, event, exception and HTTP records carry a read-only redacted flag
File sinkCrumbsFileSink.start(directory: ...) writes a rotating JSONL timeline of log, event and exception records, and writes only records whose redacted flag is true. Read it back with crumbs:files
CrumbsRedaction.redactor = (String text) => text.replaceAll(RegExp(r'\b\d{13,19}\b'), '[card]');
await CrumbsFileSink.start(directory: '${supportDir.path}/crumbs'); // supportDir is the host's choice.

MCP server and clients

The crumbs_* tools ride on the dowel MCP server, so the client config key is dowel. dart run crumbs mcp:install writes the entry into .mcp.json: ./bin/dowel mcp:serve when the fast launcher exists on a POSIX host, and dart run crumbs mcp:serve otherwise. Standard config for any client that reads .mcp.json:

{ "mcpServers": { "dowel": { "command": "./bin/dowel", "args": ["mcp:serve"], "cwd": "." } } }
ClientInstall
Claude Codeclaude mcp add dowel -- ./bin/dowel mcp:serve, then /mcp reconnect dowel after a change
Cursor.cursor/mcp.json (project) or ~/.cursor/mcp.json (user)
Windsurf~/.codeium/windsurf/mcp_config.json
Claude Desktopclaude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\)

A typical agent session, the app started with dowel_start and driven by hand or by tapir:

crumbs_clear {}
# the user (or tapir) exercises the feature
crumbs_requests {"limit": 20}
crumbs_exceptions {}
crumbs_tail {"level": "WARNING"}
crumbs_queries {}
Without crumbsWith crumbs
A stack trace scrolls past in the console; you copy it into the chat, then the agent asks for the HTTP response that caused it.The agent calls crumbs_exceptions and crumbs_requests and reads both itself.
You add print calls, hot reload and retry to see what the app sent.The agent calls crumbs_clear, the action runs again, and the next read holds only its records.

For AI coding agents

DoBecause
Install crumbs only behind if (!kReleaseMode)Anyone who reaches the VM Service of a build that carries crumbs can read every buffer
Start the app with dart run crumbs start or ./bin/dowel start, not flutter runEvery crumbs:* command and crumbs_* tool dials the session dowel records
Call crumbs_clear before a reproA buffer holds the whole run, so an old record reads like a new one
Register ExceptionWatcher (and DumpWatcher) when wiring by handCrumbsPlugin.install() installs only LogWatcher; an empty exception buffer otherwise proves nothing
Read livenessCounter with an empty crumbs_frames answerA counter that does not advance means FramePerfWatcher is not registered or the engine draws nothing, not a smooth app
Treat ******** in a record as crumbs's maskThe app sent the real credential; crumbs hid it before buffering
Set CrumbsRedaction.redactor before CrumbsFileSink.start()The sink writes only redacted records and counts the rest in droppedUnredacted
Page logs and events by passing the cursor of one answer back as since (CLI: --since, or --json --follow)crumbs_tail declares since and logger, crumbs_events declares since and type, and both answer the cursor
Point the MCP client at the dowel key and reconnect after mcp:installThe tools ride on the dowel server, and clients do not reload an entry on their own

Moving from fluttersdk_telescope

crumbs is the new name of fluttersdk_telescope, and dowel the new name of the CLI substrate it runs on. Nothing is migrated automatically:

flutter pub remove fluttersdk_telescope fluttersdk_artisan && flutter pub add crumbs dowel
mv .artisan .dowel && rm -f .dowel/plugins.json .dowel/installed/fluttersdk_telescope.json
rm bin/dispatcher.dart bin/fsa lib/app/_plugins.g.dart lib/app/commands/_index.g.dart
dart run crumbs crumbs:install
dart run dowel commands:refresh
dart run crumbs mcp:install

The old dispatcher and codegen barrels import fluttersdk_artisan, and the installer keeps a file that exists, so they go first. Rename the imports and identifiers below, and in your own commands under lib/app/commands/ replace package:fluttersdk_artisan/artisan.dart with package:dowel/dowel.dart and Artisan* with Dowel* before commands:refresh. Delete the fluttersdk entry from .mcp.json and run /mcp reconnect dowel. On a Magic app, MagicTelescopeIntegration feeds fluttersdk_telescope, not crumbs: a magic_devtools release built on crumbs ships the crumbs integration, so upgrade to it and rerun dart run crumbs crumbs:install.

BeforeAfter
package:fluttersdk_telescope/telescope.dartpackage:crumbs/crumbs.dart
Telescope* identifiers (TelescopePlugin, TelescopeStore, TelescopeRedaction, TelescopeFileSink)Crumbs* (CrumbsPlugin, CrumbsStore, CrumbsRedaction, CrumbsFileSink)
telescope:* commands, telescope_* tools, ext.telescope.*crumbs:*, crumbs_*, ext.crumbs.*
TELESCOPE_DISABLECRUMBS_DISABLE
The fluttersdk server key in .mcp.jsondowel
package:fluttersdk_artisan/artisan.dart, Artisan* in your own commandspackage:dowel/dowel.dart, Dowel*

An app that already runs an earlier crumbs release renames a few things when it upgrades. The Magic prefix is gone from the model and cache pair: the store methods are CrumbsStore.recordModel and recordCache, and the records are ModelRecord and CacheRecord. The frame buffer capacity is set with CrumbsStore.setCapacity(n, kind: CrumbsKind.framePerf), since the dedicated setter is removed. The bundled Dio adapter is removed too: build an HttpRequestRecord in your own interceptor and pass it to CrumbsStore.recordHttp. The HTTP read answers under the key requests, formerly records. CrumbsWatcher and CrumbsHttpAdapter are abstract interface classes, so an adapter or watcher implements them, and pendingCount has no default body.

The changelog lists the rest.

Dependencies

dowel for the CLI, the MCP server and the VM Service connection; logging for the log watcher; meta. The rest is the Flutter SDK. HTTP libraries stay out: the app adds dio or any other client itself.

Links

License

MIT, see LICENSE. Built by Anılcan Çakır.