{"id":51148763,"url":"https://github.com/fluttersdk/telescope","last_synced_at":"2026-06-26T04:30:31.961Z","repository":{"id":359201371,"uuid":"1244990840","full_name":"fluttersdk/telescope","owner":"fluttersdk","description":"Passive runtime inspector for Flutter. Captures HTTP, logs, exceptions, DB queries; surfaces to CLI and to AI agents (Claude Code) via MCP. Debug-only, zero release overhead.","archived":false,"fork":false,"pushed_at":"2026-06-25T10:54:24.000Z","size":966,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-25T12:20:42.421Z","etag":null,"topics":["anthropic","claude-code","dart","developer-tools","flutter","flutter-devtools","llm-tools","mcp","mcp-server","model-context-protocol","runtime-observability","vm-service"],"latest_commit_sha":null,"homepage":"https://fluttersdk.com/telescope","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fluttersdk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-20T19:57:25.000Z","updated_at":"2026-06-25T10:54:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fluttersdk/telescope","commit_stats":null,"previous_names":["fluttersdk/telescope"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/fluttersdk/telescope","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluttersdk%2Ftelescope","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluttersdk%2Ftelescope/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluttersdk%2Ftelescope/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluttersdk%2Ftelescope/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fluttersdk","download_url":"https://codeload.github.com/fluttersdk/telescope/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluttersdk%2Ftelescope/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34803678,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","claude-code","dart","developer-tools","flutter","flutter-devtools","llm-tools","mcp","mcp-server","model-context-protocol","runtime-observability","vm-service"],"created_at":"2026-06-26T04:30:24.291Z","updated_at":"2026-06-26T04:30:31.916Z","avatar_url":"https://github.com/fluttersdk.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/fluttersdk/telescope/master/.github/telescope-logo.svg\" width=\"120\" alt=\"Telescope Logo\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eTelescope\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003ePassive runtime inspector for Flutter. Read by humans, queried by AI agents.\u003c/strong\u003e\u003cbr/\u003e\n  HTTP, logs, exceptions, \u003ccode\u003edebugPrint\u003c/code\u003e, DB queries, and Magic events captured over VM Service extensions, surfaced as \u003ccode\u003etelescope:*\u003c/code\u003e CLI commands and as 9 MCP tools for Claude Code.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pub.dev/packages/fluttersdk_telescope\"\u003e\u003cimg src=\"https://img.shields.io/pub/v/fluttersdk_telescope.svg\" alt=\"pub package\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/fluttersdk/telescope/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/fluttersdk/telescope/ci.yml?branch=master\u0026label=CI\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pub.dev/packages/fluttersdk_telescope/score\"\u003e\u003cimg src=\"https://img.shields.io/pub/points/fluttersdk_telescope\" alt=\"pub points\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/fluttersdk/telescope/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/fluttersdk/telescope?style=flat\" alt=\"GitHub stars\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://fluttersdk.com/telescope\"\u003eDocumentation\u003c/a\u003e ·\n  \u003ca href=\"https://pub.dev/packages/fluttersdk_telescope\"\u003epub.dev\u003c/a\u003e ·\n  \u003ca href=\"https://github.com/fluttersdk/telescope/issues\"\u003eIssues\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Why Telescope?\n\n**Stop pasting stack traces into Claude. Let your agent read them itself.**\n\nDebugging 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.\n\n**Telescope closes that loop.** Passive watchers and 11 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; **9 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.\n\n```bash\n# One-shot self-bootstrap install (works from a fresh consumer)\nflutter pub add fluttersdk_telescope\ndart run fluttersdk_telescope telescope:install\n```\n\nThe 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.\n\nAfter 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 \u003ccmd\u003e` keeps working as a slower (~3s cold) fallback.\n\n## Features\n\n| | Feature | Description |\n|:--|:--------|:------------|\n| 👁 | **9 Watchers** | LogWatcher, ExceptionWatcher, DumpWatcher, plus 6 Magic-specific adapters covering HTTP, models, cache, events, gates, and DB queries |\n| 🤖 | **9 MCP Tools** | `telescope_requests`, `telescope_tail`, `telescope_exceptions`, `telescope_events`, `telescope_gates`, `telescope_dumps`, `telescope_queries`, `telescope_caches`, `telescope_clear` |\n| 🖥 | **6 CLI Commands** | `telescope:install`, `telescope:tail`, `telescope:requests`, `telescope:queries`, `telescope:caches`, `telescope:clear` |\n| 🔌 | **Adapter Contract** | `TelescopeHttpAdapter` (abstract, 3-method shape) for plugging any HTTP client; ships `DioHttpAdapter` for vanilla Dio |\n| 📋 | **9 Record Types** | Immutable: `HttpRequestRecord`, `LogRecordEntry`, `ExceptionRecord`, `MagicModelRecord`, `MagicCacheRecord`, `EventRecord`, `GateRecord`, `DumpRecord`, `QueryRecord` |\n| 📡 | **VM Service Extensions** | 11 extensions: `ext.telescope.requests`, `.console`, `.exceptions`, `.events`, `.gates`, `.dumps`, `.queries`, `.caches`, `.clear`, `.pause`, `.resume` |\n| ✨ | **Magic Integration** | `MagicTelescopeIntegration.install()` wires Http facade adapter + model/cache/event/gate watchers in one call (ships in the `magic_devtools` dev_dependency) |\n| 🔒 | **Debug-only Gate** | Consumer wraps install inside `if (kDebugMode)`; release builds tree-shake the entire telescope branch on all platforms |\n| 🔄 | **Idempotent Install** | Every `registerExtension` call routes through `registerExtensionIdempotent`; hot-restart safe, no `ArgumentError` on re-registration |\n\n## Quick Start\n\n### Option A (recommended): one-shot install\n\nAdd 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:\n\n```bash\nflutter pub add fluttersdk_telescope\ndart run fluttersdk_telescope telescope:install\n```\n\nThe 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.\n\nFor everyday repeat usage, the consumer's `./bin/fsa` (artisan native AOT binary built during install) gives ~110ms warm startup:\n\n```bash\n./bin/fsa telescope:tail\n./bin/fsa telescope:requests\n```\n\n`dart run fluttersdk_telescope \u003ccmd\u003e` remains a slower (~3s cold) fallback that always works without the AOT bundle.\n\n### Option B: manual wiring\n\n#### 1. Add the dependency\n\n```yaml\n# pubspec.yaml\ndependencies:\n  fluttersdk_telescope: ^0.0.4\n```\n\n#### 2. Install in `main.dart`\n\nInstall 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.\n\n```dart\nimport 'package:flutter/foundation.dart';\nimport 'package:fluttersdk_telescope/telescope.dart';\nimport 'package:magic_devtools/telescope.dart'; // magic_devtools dev_dependency (Magic-stack apps only)\n\nvoid main() async {\n  WidgetsFlutterBinding.ensureInitialized();\n\n  // 1. Install Telescope core (auto-installs LogWatcher + registers VM extensions).\n  if (kDebugMode) {\n    TelescopePlugin.install();\n\n    // 2. Opt-in watchers registered after install().\n    TelescopePlugin.registerWatcher(ExceptionWatcher());\n    TelescopePlugin.registerWatcher(DumpWatcher());\n  }\n\n  // 3. Magic-side adapters run AFTER Magic.init() because they resolve\n  //    framework internals (Http facade, Gate manager) from the IoC container.\n  await Magic.init(configFactories: [...]);\n\n  if (kDebugMode) {\n    // MagicTelescopeIntegration ships in magic_devtools (not magic core).\n    // Add magic_devtools to dev_dependencies in pubspec.yaml.\n    MagicTelescopeIntegration.install();\n  }\n\n  runApp(MyApp());\n}\n```\n\n#### 3. Register the Artisan provider (MCP tools)\n\nIn 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:\n\n```dart\nimport 'package:fluttersdk_artisan/artisan.dart';\nimport 'package:fluttersdk_telescope/cli.dart' show FluttersdkTelescopeArtisanProvider;\n\nexit(await runArtisan(\n  args,\n  baseProviders: [\n    FluttersdkTelescopeArtisanProvider(),\n    // ...other providers (DuskArtisanProvider, etc.)\n  ],\n));\n```\n\n## Watchers\n\n| Watcher | Captures | Auto-install? | Notes |\n|---------|----------|---------------|-------|\n| `LogWatcher` | All `package:logging` Logger calls | Yes | Installed automatically by `TelescopePlugin.install()`. |\n| `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.). |\n| `DumpWatcher` | `debugPrint` + `print` output | No | Overrides `debugPrint` globally; chain-preserves previous override. Active in debug mode only. |\n| `MagicHttpFacadeAdapter` | HTTP traffic through the Magic `Http` facade | No | Register via `TelescopePlugin.registerHttpAdapter(MagicHttpFacadeAdapter())`. Requires Magic framework. |\n| `MagicModelWatcher` | Magic Eloquent model `create`, `save`, `delete` lifecycle events | No | Register via `TelescopePlugin.registerWatcher(MagicModelWatcher())`. Requires Magic framework. |\n| `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. |\n| `MagicEventWatcher` | Events dispatched through the Magic `Event` facade | No | Register via `TelescopePlugin.registerWatcher(MagicEventWatcher())`. Requires Magic framework. |\n| `MagicGateWatcher` | `Gate.allows` / `Gate.denies` authorization checks | No | Register via `TelescopePlugin.registerWatcher(MagicGateWatcher())`. Requires Magic framework. |\n| `MagicQueryWatcher` | Magic SQLite + remote DB queries (sql, bindings, timeMs, connection) | No | Subscribes to the magic-side `QueryExecuted` event dispatched by the database connector. Requires Magic framework. |\n\n## MCP Tools\n\nExposed via `TelescopeArtisanProvider` when the consumer registers it (auto-wired by `telescope:install` through `lib/app/_plugins.g.dart` + `bin/dispatcher.dart`). All tools route through `ext.telescope.*` VM Service extensions and require a running Flutter app.\n\n| Tool | Extension method | Captures |\n|------|-----------------|----------|\n| `telescope_tail` | `ext.telescope.console` | Log ring buffer (`package:logging` records); filter by level + limit. |\n| `telescope_requests` | `ext.telescope.requests` | HTTP request ring buffer (method, URL, status, duration, headers, body snippet). |\n| `telescope_exceptions` | `ext.telescope.exceptions` | Uncaught exception ring buffer (type, message, stack trace). |\n| `telescope_clear` | `ext.telescope.clear` | Wipes all ring buffers atomically. No parameters. |\n| `telescope_events` | `ext.telescope.events` | In-app event ring buffer (Magic `Event.dispatch` calls; event type + payload). |\n| `telescope_gates` | `ext.telescope.gates` | Gate authorization check ring buffer (ability, result, user id, argument type). |\n| `telescope_dumps` | `ext.telescope.dumps` | `debugPrint` output ring buffer (message + timestamp). |\n| `telescope_queries` | `ext.telescope.queries` | DB query ring buffer (sql, bindings, timeMs, connectionName). |\n| `telescope_caches` | `ext.telescope.caches` | Cache operation ring buffer (operation: hit / miss / put / forget / flush; key; ttlMs). |\n\n## CLI Commands\n\nRegistered via `TelescopeArtisanProvider.commands()`. After `telescope:install` you can invoke any command three ways: through the consumer's fast-cli (`./bin/fsa \u003ccommand\u003e`, recommended), through telescope's standalone bin (`dart run fluttersdk_telescope \u003ccommand\u003e`), or through the consumer dispatcher fallback (`dart run fluttersdk_artisan \u003ccommand\u003e`).\n\n| Command | Purpose |\n|---------|---------|\n| `telescope:install` | One-shot bootstrap: scaffolds consumer artisan harness, runs `plugin:install fluttersdk_telescope`, and injects `TelescopePlugin.install()` into `lib/main.dart`. Detects Magic-stack apps via the `await Magic.init(` anchor and injects BEFORE Magic.init; falls back to `runApp(` for vanilla Flutter. |\n| `telescope:tail` | Stream the log buffer. Filter by level + limit. |\n| `telescope:requests` | Print the HTTP request buffer (paginated). |\n| `telescope:queries` | Print the DB query buffer (paginated). |\n| `telescope:caches` | Print the cache operation buffer (paginated). |\n| `telescope:clear` | Flush all buffers atomically. |\n\n## Examples\n\n### `example/`\n\nVanilla Flutter app (no Magic framework) that exercises every framework-agnostic capture surface: HTTP traffic via the Telescope Dio interceptor, log output via `package:logging`, uncaught exceptions via `ExceptionWatcher`, and `debugPrint` output via `DumpWatcher`. Demonstrates the minimal install pattern and the in-app overlay dashboard.\n\n```bash\ncd example \u0026\u0026 flutter run -d chrome\n```\n\n## Architecture\n\nTelescope is subsystem-first under `lib/src/`, every directory owns a single concern:\n\n```\nlib/\n├── telescope.dart              # Single barrel, re-exports the full public API\n├── cli.dart                    # Flutter-free codegen barrel (FluttersdkTelescopeArtisanProvider typedef)\n└── src/\n    ├── watchers/               # TelescopeWatcher abstract contract + LogWatcher, ExceptionWatcher, DumpWatcher\n    ├── adapters/               # TelescopeHttpAdapter abstract contract + DioHttpAdapter concrete impl\n    ├── records/                # Immutable record types: HttpRequestRecord, LogRecordEntry, ExceptionRecord, etc.\n    ├── extensions/             # registerAllTelescopeExtensions() aggregator + per-concern VM Service handlers\n    ├── commands/               # TelescopeInstallCommand + 5 tail/query/clear commands\n    ├── telescope_store.dart    # 9-buffer ring store (singleton); Queue\u003cT\u003e per buffer + broadcast StreamController\u003cT\u003e\n    ├── telescope_plugin.dart   # TelescopePlugin.install() entry + registerHttpAdapter() + registerWatcher()\n    └── telescope_artisan_provider.dart  # TelescopeArtisanProvider: 6 commands + 9 MCP tool descriptors\n```\n\nBoot flow:\n\n```\nTelescopePlugin.install()\n    ↓\nRegister default watchers (LogWatcher auto-installs)\n    ↓\nregisterAllTelescopeExtensions()   # 11 ext.telescope.* VM Service extensions, idempotent\n    ↓\nConsumer registers TelescopeArtisanProvider (auto-wired by `telescope:install` via bin/dispatcher.dart + _plugins.g.dart)\n    ↓\nartisan mcp:serve   -\u003e   9 telescope_* tools surface to MCP clients (Claude Code, Cursor, etc.)\n```\n\nEvery concrete watcher and record type is a `final class`. The two adapter contracts (`TelescopeWatcher`, `TelescopeHttpAdapter`) are `abstract class` with frozen 3-method signatures (`name`, `install`, `uninstall`). Magic-side glue (`MagicHttpFacadeAdapter`, `MagicModelWatcher`, etc.) depends on these contracts; any signature change requires a coordinated bump across both repos.\n\n## Compared to\n\n| Tool | What it does | Where telescope wins |\n|---|---|---|\n| **[Sentry Flutter](https://pub.dev/packages/sentry_flutter)** | Production crash + perf reporting via external SaaS | Local-only; debug-only; CLI + MCP queryable from your agent; no DSN, no SaaS account |\n| **[Talker / talker_flutter](https://pub.dev/packages/talker_flutter)** | In-app log overlay, Dio interceptor | VM Service surface (queryable by tools); MCP server for AI agents; framework-aware model / cache / event / gate watchers |\n| **[Alice](https://pub.dev/packages/alice)** | In-app HTTP request overlay UI | Captures 9 buffers (not just HTTP); passive (no shake-to-open overlay); CLI streaming; AI agent access; debug tree-shake |\n| **[Flutter DevTools](https://docs.flutter.dev/tools/devtools/overview)** | Official browser-based inspector | Programmatic access (CLI + MCP), not just human-via-browser; ring-buffered records you can query between iterations; domain-aware (Magic) watchers |\n| **[mcp_flutter](https://github.com/Arenukvern/mcp_flutter)** | MCP toolkit for AI-driven UI interaction (tap, scroll, snapshot) | Complementary, not competitive: telescope owns runtime telemetry (HTTP, exceptions, queries); mcp_flutter owns UI automation |\n\n## AI Agent Integration\n\nTelescope is the first Flutter MCP server focused on **runtime observability** (HTTP, exceptions, queries, cache) rather than UI automation. The 9 `telescope_*` tools give Claude Code, Cursor, Codex, or any MCP-compatible agent direct read access to every runtime buffer: inspect HTTP traffic without a proxy, read logs without grepping output, catch exceptions without scrolling DevTools.\n\n### One-line `.mcp.json` install\n\n`telescope:install` auto-writes `.mcp.json` for you. Or wire it manually for any MCP-compatible client:\n\n```jsonc\n// .mcp.json (project root) — Claude Code / Codex / Cursor / Goose / VS Code Copilot\n{\n  \"mcpServers\": {\n    \"fluttersdk\": {\n      \"command\": \"./bin/fsa\",\n      \"args\": [\"mcp:serve\"],\n      \"cwd\": \".\"\n    }\n  }\n}\n```\n\nAfter this, restart your MCP client. The 9 `telescope_*` tools (plus the substrate's `artisan_*` tools) surface automatically in `/mcp`.\n\n### Before / after\n\n| Without telescope | With telescope |\n|---|---|\n| Stack trace appears in your console. You copy it. You paste it into Claude. Claude asks for the HTTP response that triggered it. You scroll, copy, paste. | Claude calls `telescope_exceptions` → reads the last 500 captured exceptions with timestamps + stack traces. Claude calls `telescope_requests` → reads matched HTTP records. Claude proposes the fix. |\n| You hot-reload, retry, paste again. | Claude calls `telescope_clear` between iterations. The fix loop closes without you in the middle. |\n\n### Typical agent session\n\n```\n[agent] artisan_start { device: chrome }          // launch the app\n[agent] \u003cexercise the feature under inspection\u003e\n[agent] telescope_requests {}                     // inspect all HTTP calls made\n[agent] telescope_tail { level: warning }         // filter logs to warnings and above\n[agent] telescope_exceptions {}                   // check for any uncaught exceptions\n[agent] telescope_queries {}                      // review DB queries and timings\n[agent] telescope_clear {}                        // flush buffers before the next scenario\n[agent] artisan_stop                              // tear down\n```\n\nFor agents that read structured project context at attach time, the canonical entry point is [`llms.txt`](llms.txt) at the repo root (also published at `https://fluttersdk.com/telescope/llms.txt`). It enumerates the watcher surface, the VM extension catalog, and every MCP tool input schema in agent-readable form.\n\n## Documentation\n\nFull docs with live examples at **[fluttersdk.com/telescope](https://fluttersdk.com/telescope)**.\n\n| Topic | |\n|:------|:-|\n| [Getting Started](https://fluttersdk.com/telescope/getting-started/) | Overview, requirements, first install |\n| [Watchers](https://fluttersdk.com/telescope/watchers/) | All 9 watchers: setup, chain-preserve pattern, Magic adapters |\n| [MCP Tools](https://fluttersdk.com/telescope/mcp/) | Every tool, every input schema, filter parameters |\n\n## Contributing\n\n```bash\ngit clone https://github.com/fluttersdk/telescope.git\ncd telescope \u0026\u0026 dart pub get\nflutter test \u0026\u0026 dart analyze\n```\n\nThe baseline is 249 tests green (post magic-dev-dep drop). New behavior ships with the matching test (red, green, refactor). `dart format lib/ test/ bin/` must produce no diff and `dart analyze` must report zero issues across `lib/`, `test/`, and `bin/`.\n\nBefore opening a pull request, also run:\n\n```bash\ndart format lib/ test/ bin/         # zero diff\ndart analyze                         # zero issues\ndart pub publish --dry-run           # validate the publish archive\n```\n\n[Report a bug](https://github.com/fluttersdk/telescope/issues/new?template=bug_report.yml) · [Request a feature](https://github.com/fluttersdk/telescope/issues/new?template=feature_request.yml)\n\n## Inspiration\n\nTelescope is inspired by [**Laravel Telescope**](https://laravel.com/docs/telescope), the elegant developer-tools assistant for Laravel that records every request, exception, log, query, cache hit, and event into a queryable timeline. The same pattern, ported to Flutter, with two additions that make sense for 2026: a CLI-first surface for terminal-native developers and a 9-tool MCP server so AI coding agents can read the timeline directly.\n\n## Part of the Magic SDK suite\n\nTelescope is one of seven packages in the [FlutterSDK Magic suite](https://fluttersdk.com), a Laravel-inspired Flutter ecosystem:\n\n- **[magic](https://pub.dev/packages/magic)** — Laravel-style framework (facades, ORM, providers, controllers, routing)\n- **[wind](https://pub.dev/packages/fluttersdk_wind)** — Tailwind-style className UI primitives for Flutter\n- **[fluttersdk_artisan](https://pub.dev/packages/fluttersdk_artisan)** — Pure Dart CLI + MCP substrate that telescope extends\n- **[fluttersdk_dusk](https://pub.dev/packages/fluttersdk_dusk)** — E2E gesture / snapshot driver via VM extensions\n- **fluttersdk_telescope** (this package) — Runtime observability via VM extensions + MCP\n- **[magic_tinker](https://pub.dev/packages/magic_tinker)** — Connected REPL into the running app\n- **[magic_starter](https://pub.dev/packages/magic_starter)** — Auth / profile / teams scaffolding\n\n## License\n\nMIT, see [LICENSE](LICENSE) for details.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eBuilt with care by \u003ca href=\"https://github.com/fluttersdk\"\u003eFlutterSDK\u003c/a\u003e\u003c/sub\u003e\u003cbr/\u003e\n  \u003csub\u003eIf Telescope saves you debugging time, \u003ca href=\"https://github.com/fluttersdk/telescope\"\u003egive it a star\u003c/a\u003e, it helps others discover it.\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluttersdk%2Ftelescope","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffluttersdk%2Ftelescope","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluttersdk%2Ftelescope/lists"}