FlutterSDK Telescope

Telescope

Passive runtime inspector for Flutter. Read by humans, queried by AI agents.

HTTP, logs, exceptions, debugPrint , DB queries, and Magic events captured over VM Service extensions, surfaced as telescope:* CLI commands and as 10 MCP tools for Claude Code.

Documentation · pub.dev · Issues

---

Why Telescope?

Stop pasting stack traces into Claude. Let your agent read them itself.

Debugging a running Flutter app has always required a mix of print statements, custom logging sinks, and network proxies that each tell a different slice of the story. When something breaks, you stitch together log files, Charles captures, and Flutter DevTools windows to reconstruct what happened. The AI workflow is worse: you copy the stack trace out of the console, paste it into Claude Code, copy the failing HTTP response, paste it back, repeat.

Telescope closes that loop. Passive watchers and 14 VM Service extensions register at startup. Every HTTP request, log line, exception, debugPrint call, DB query, and Magic-framework lifecycle event lands in a ring buffer. CLI commands (telescope:tail, telescope:requests) stream the buffers for humans; 10 MCP tools (telescope_requests, telescope_exceptions, telescope_tail, ...) expose the same buffers to AI coding agents like Claude Code, Cursor, and Codex. No copy-paste, no screenshots, no SaaS account. Development-only; a kDebugMode or !kReleaseMode guard at the call site tree-shakes the entire subsystem on release builds.

# One-shot self-bootstrap install (works from a fresh consumer)

flutter pub add fluttersdk_telescope dart run fluttersdk_telescope telescope:install

The install command scaffolds the consumer artisan harness if it is missing, runs plugin:install fluttersdk_telescope, and patches lib/main.dart so TelescopePlugin.install() runs before Magic.init() (or before runApp on vanilla Flutter). Everything is gated under kDebugMode; release builds tree-shake the entire subsystem.

After install, the consumer gets the artisan fast-cli at ./bin/fsa (native AOT, ~110ms warm startup) for every subsequent telescope command. dart run fluttersdk_telescope keeps working as a slower (~3s cold) fallback.

Features

Quick Start

Option A (recommended): one-shot install

Add the dependency, then let telescope bootstrap itself via its own CLI entry point. No prior fluttersdk_artisan wiring is required; telescope's binary carries the artisan substrate so the install works from a fresh consumer:

flutter pub add fluttersdk_telescope

dart run fluttersdk_telescope telescope:install

The command scaffolds the consumer artisan harness if it's missing (bin/dispatcher.dart + lib/app/_plugins.g.dart), runs plugin:install fluttersdk_telescope, and patches lib/main.dart so TelescopePlugin.install() runs before Magic.init() (or before runApp on vanilla Flutter). Idempotent; safe to re-run.

For everyday repeat usage, the consumer's ./bin/fsa (artisan native AOT binary built during install) gives ~110ms warm startup:

./bin/fsa telescope:tail

./bin/fsa telescope:requests

dart run fluttersdk_telescope remains a slower (~3s cold) fallback that always works without the AOT bundle.

Option B: manual wiring

1. Add the dependency

# pubspec.yaml

dependencies: fluttersdk_telescope: ^0.0.4

2. Install in main.dart

Install Telescope before Magic.init() (or before runApp for plain Flutter). Wrap every install call in a mode guard at the call site so the entire tooling branch is tree-shaken in release builds: kDebugMode, which is what telescope:install writes, or !kReleaseMode, which also keeps profile builds (what a performance measurement needs, and what magic_devtools uses).

import 'package:flutter/foundation.dart';

import 'package:fluttersdk_telescope/telescope.dart'; import 'package:magic_devtools/telescope.dart'; // magic_devtools dev_dependency (Magic-stack apps only)

void main() async { WidgetsFlutterBinding.ensureInitialized();

// 1. Install Telescope core (auto-installs LogWatcher + registers VM extensions). if (!kReleaseMode) { TelescopePlugin.install();

// 2. Opt-in watchers registered after install(). TelescopePlugin.registerWatcher(ExceptionWatcher()); TelescopePlugin.registerWatcher(DumpWatcher()); }

// 3. Magic-side adapters run AFTER Magic.init() because they resolve // framework internals (Http facade, Gate manager) from the IoC container. await Magic.init(configFactories: [...]);

if (!kReleaseMode) { // MagicTelescopeIntegration ships in magic_devtools (not magic core). // Add magic_devtools to dev_dependencies in pubspec.yaml. MagicTelescopeIntegration.install(); }

runApp(MyApp()); }

3. Register the Artisan provider (MCP tools)

In the consumer's bin/dispatcher.dart (generated by dart run fluttersdk_artisan install), telescope is auto-discovered through lib/app/_plugins.g.dart after plugin:install fluttersdk_telescope. If you are wiring providers by hand, add FluttersdkTelescopeArtisanProvider() to the baseProviders list so the 10 telescope_* MCP tools are visible to Claude Code and other MCP clients:

import 'package:fluttersdk_artisan/artisan.dart';

import 'package:fluttersdk_telescope/cli.dart' show FluttersdkTelescopeArtisanProvider;

exit(await runArtisan( args, baseProviders: [ FluttersdkTelescopeArtisanProvider(), // ...other providers (DuskArtisanProvider, etc.) ], ));

Watchers

MCP Tools

Exposed via TelescopeArtisanProvider when the consumer registers it (auto-wired by telescope:install through lib/app/_plugins.g.dart + bin/dispatcher.dart