Getting Started

Pick your path#

What crumbs is#

crumbs is a passive runtime inspector for Flutter apps. Watchers and HTTP adapters record what the app does into in-memory ring buffers, and ext.crumbs.* VM Service extensions serve those buffers to crumbs:* CLI commands and crumbs_* MCP tools on dowel. It never changes app behaviour; it only records.

flutter pub add crumbs
dart run crumbs crumbs:install

crumbs:install scaffolds the dowel harness when it is missing, registers the plugin and patches lib/main.dart so CrumbsPlugin.install() runs at startup inside a kDebugMode guard. The guard belongs to the call site: kDebugMode is what the installer writes, and !kReleaseMode also keeps crumbs in profile builds (see Call-site guard). A release build tree-shakes crumbs either way.

Requirements#

What gets captured#

After crumbs:install on any Flutter app:

• Logs: every package:logging record, through LogWatcher (installed by CrumbsPlugin.install()).
• Exceptions: uncaught errors, through ExceptionWatcher, chained to any handler already set (Sentry, Bugsnag).
• debugPrint output: through DumpWatcher, chained to the previous override.

With the Magic stack (MagicCrumbsIntegration.install() after Magic.init()):

• HTTP traffic through the Magic Http facade.
• Model lifecycle: created, saved and deleted events on Magic models.
• Cache operations: hit, miss, put, forget and flush through the Cache facade.
• In-app events: a curated set of Magic auth, database and gate-definition events.
• Gate checks: every Gate.allows and Gate.denies result with the user id.
• DB queries: SQL, bindings and execution time through the Magic query builder.

FramePerfWatcher (frame timings) and a Dio interceptor (HTTP on a vanilla app) are opt-in on any app; see Watchers.

Host features#

• Redaction: the credential lists and CrumbsRedaction.redactor, the host hook that masks every log, event, exception and HTTP record at insert.
• File sink: CrumbsFileSink, a rotating JSONL timeline on disk that writes only redacted records, read back through crumbs:files.
• Buffers: per-kind capacity with CrumbsStore.setCapacity, the atUs clock, and how limit and minLevel behave.
• Cursor and filters: since, type, logger and cursor on the read extensions, and --json and --follow on the CLI.

Related Documentation#

• Installation: the installer, manual wiring and the dowel provider.
• Quickstart: install, start the app and make the first MCP tool call.
• Watchers: every watcher and adapter, and the call-site guard.
• MCP overview: how the crumbs_* tools reach the running app.