telescope

<p align="center">
  <img src="https://raw.githubusercontent.com/fluttersdk/telescope/master/.github/telescope-logo.svg" width="120" alt="Telescope Logo" />
</p>

<h1 align="center">Telescope</h1>

<p align="center">
  <strong>Passive runtime inspector for Flutter. Read by humans, queried by AI agents.</strong><br/>
  HTTP, logs, exceptions, <code>debugPrint</code>, DB queries, and Magic events captured over VM Service extensions, surfaced as <code>telescope:*</code> CLI commands and as 10 MCP tools for Claude Code.
</p>

<p align="center">
  <a href="https://pub.dev/packages/fluttersdk_telescope"><img src="https://img.shields.io/pub/v/fluttersdk_telescope.svg" alt="pub package"></a>
  <a href="https://github.com/fluttersdk/telescope/actions"><img src="https://img.shields.io/github/actions/workflow/status/fluttersdk/telescope/ci.yml?branch=master&label=CI" alt="CI"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
  <a href="https://pub.dev/packages/fluttersdk_telescope/score"><img src="https://img.shields.io/pub/points/fluttersdk_telescope" alt="pub points"></a>
  <a href="https://github.com/fluttersdk/telescope/stargazers"><img src="https://img.shields.io/github/stars/fluttersdk/telescope?style=flat" alt="GitHub stars"></a>
</p>

<p align="center">
  <a href="https://fluttersdk.com/telescope">Documentation</a> ·
  <a href="https://pub.dev/packages/fluttersdk_telescope">pub.dev</a> ·
  <a href="https://github.com/fluttersdk/telescope/issues">Issues</a>
</p>

---

## 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 12 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. Debug-only; `kDebugMode` tree-shakes the entire subsystem on release builds.

```bash
# 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 <cmd>` keeps working as a slower (~3s cold) fallback.

## Features

| | Feature | Description |
|:--|:--------|:------------|
| 👁 | **10 Watchers** | LogWatcher, ExceptionWatcher, DumpWatcher, FramePerfWatcher, plus 6 Magic-specific adapters covering HTTP, models, cache, events, gates, and DB queries |
| 🤖 | **10 MCP Tools** | `telescope_requests`, `telescope_tail`, `telescope_exceptions`, `telescope_events`, `telescope_gates`, `telescope_dumps`, `telescope_queries`, `telescope_caches`, `telescope_frames`, `telescope_clear` |
| 🖥 | **7 CLI Commands** | `telescope:install`, `telescope:tail`, `telescope:requests`, `telescope:queries`, `telescope:caches`, `telescope:frames`, `telescope:clear` |
| 🔌 | **Adapter Contract** | `TelescopeHttpAdapter` (abstract, 3-method shape) for plugging any HTTP client; ships `DioHttpAdapter` for vanilla Dio |
| 📋 | **10 Record Types** | Immutable: `HttpRequestRecord`, `LogRecordEntry`, `ExceptionRecord`, `MagicModelRecord`, `MagicCacheRecord`, `EventRecord`, `GateRecord`, `DumpRecord`, `QueryRecord`, `FramePerfRecord` |
| 📡 | **VM Service Extensions** | 12 extensions: `ext.telescope.requests`, `.console`, `.exceptions`, `.events`, `.gates`, `.dumps`, `.queries`, `.caches`, `.frames`, `.clear`, `.pause`, `.resume` |
| ✨ | **Magic Integration** | `MagicTelescopeIntegration.install()` wires Http facade adapter + model/cache/event/gate watchers in one call (ships in the `magic_devtools` dev_dependency) |
| 🔒 | **Debug-only Gate** | Consumer wraps install inside `if (kDebugMode)`; release builds tree-shake the entire telescope branch on all platforms |
| 🔄 | **Idempotent Install** | Every `registerExtension` call routes through `registerExtensionIdempotent`; hot-restart safe, no `ArgumentError` on re-registration |

## 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:

```bash
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:

```bash
./bin/fsa telescope:tail
./bin/fsa telescope:requests
```

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

### Option B: manual wiring

#### 1. Add the dependency

```yaml
# 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 `kDebugMode` so the entire tooling branch is tree-shaken in release builds.

```dart
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 (kDebugMode) {
    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 (kDebugMode) {
    // 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 9 `telescope_*` MCP tools are visible to Claude Code and other MCP clients:

```dart
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

| Watcher | Captures | Auto-install? | Notes |
|---------|----------|---------------|-------|
| `LogWatcher` | All `package:logging` Logger calls | Yes | Installed automatically by `TelescopePlugin.install()`. |
| `ExceptionWatcher` | Unhandled exceptions via `FlutterError.onError` + `PlatformDispatcher.onError` | No | Call `TelescopePlugin.registerWatcher(ExceptionWatcher())` after install. Both hooks chain-preserve any previously registered handler (Sentry, Bugsnag, etc.). |
| `DumpWatcher` | `debugPrint` + `print` output | No | Overrides `debugPrint` globally; chain-preserves previous override. Active in debug mode only. |
| `MagicHttpFacadeAdapter` | HTTP traffic through the Magic `Http` facade | No | Register via `TelescopePlugin.registerHttpAdapter(MagicHttpFacadeAdapter())`. Requires Magic framework. |
| `MagicModelWatcher` | Magic Eloquent model `create`, `save`, `delete` lifecycle events | No | Register via `TelescopePlugin.registerWatcher(MagicModelWatcher())`. Requires Magic framework. |
| `MagicCacheWatcher` | `Cache.get` / `put` / `forget` / `flush` (hit + miss + put + forget + flush operations) | No | Subscribes to magic-side `CacheHit` / `CacheMiss` / `CachePut` / `CacheForget` / `CacheFlush` events. Requires Magic framework. |
| `MagicEventWatcher` | Events dispatched through the Magic `Event` facade | No | Register via `TelescopePlugin.registerWatcher(MagicEventWatcher())`. Requires Magic framework. |
| `MagicGateWatcher` | `Gate.allows` / `Gate.denies` authorization checks | No | Register via `TelescopePlugin.registerWatcher(MagicGateWatcher())`. Requires Magic framework. |
| `MagicQueryWatcher` | Magic SQLite + remote DB