Skip to content
Back to search

flutter-map

A Flutter agent skill and toolchain that produces a visual navigation map of a Flutter app

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tayormi--flutter-map/badge.svg)](/listings/tayormi--flutter-map)

HTML

<a href="/listings/tayormi--flutter-map"><img src="/api/listings/tayormi--flutter-map/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

cd packages/flutter_map_parser
dart pub get
dart test

# parse + pack (static, no simulator)
dart run bin/flutter_map.dart ../../fixtures/demo_go_router

# parse + prepare deep-link explore stubs
dart run bin/prepare_explore.dart ../../fixtures/demo_go_router

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 222 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # flutter-map
  2. A Flutter agent skill and toolchain that produces a **visual navigation map of
  3. a Flutter app**: every route as a card with a real screenshot, runtime state
  4. variants such as sheets and dialogs, navigation edges between screens, and
  5. replayable [Argent](https://argent.swmansion.com) flows showing how each screen
  6. was reached.
  7. The result is packaged as a portable, producer-neutral `.appmap` bundle
  8. compatible with [expo-map](https://github.com/aleqsio/expo-map), and can be
  9. explored in the included interactive Flutter visualiser.
  10. ## How it works
  11. ```
  12. ┌──────────────┐ ┌───────────────────┐ ┌────────────┐ ┌──────────────┐
  13. │ 1. parse │ ──▶ │ 2. explore │ ──▶ │ 3. pack │ ──▶ │ 4. visualise │
  14. │ Flutter code │ │ simulator/emulator│ │ .appmap zip│ │ Flutter web │
  15. └──────────────┘ └───────────────────┘ └────────────┘ └──────────────┘
  16. routes, edges, screenshots, states, manifest, map, graph, flows,
  17. params, state hints navigation flows screens, flows replay overlays
  18. ```
  19. 1. **Parse:** statically inspect GoRouter, go_router_builder, AutoRoute,
  20. Navigator 1.0, or Navigator 2.0 code to discover routes, parameters,
  21. navigation edges, deep-link schemes, and runtime-state hints.
  22. 2. **Explore:** open each route on an iOS Simulator or Android emulator,
  23. capture what really rendered, classify redirects and failures, trigger safe
  24. runtime states, and record navigation paths as Argent flows.
  25. 3. **Pack:** merge the graph, capture verdicts, screenshots, state variants,
  26. and replay metadata into an expo-map-compatible `.appmap` archive.
  27. 4. **Visualise:** inspect the graph, distinguish code-declared and
  28. agent-observed edges, follow recorded flows, and review interaction markers
  29. on the exact captured screen state.
  30. ## Visualiser (Flutter web)
  31. **Hosted visualiser:**
  32. [flutter-map-visualiser.onrender.com](https://flutter-map-visualiser.onrender.com/)
  33. To run it locally:
  34. ```bash
  35. cd apps/flutter_map_visualiser
  36. flutter pub get
  37. flutter run -d chrome
  38. ```
  39. The bundled Bluesky demo opens automatically with 70 routes, 126 flows, and 85
  40. screenshots, including 15 runtime-state variants. Of its 70 base captures, 58
  41. are healthy screens or intentional empty states; the remaining captures
  42. document loading, not-found, error-boundary, and auth-wall outcomes.
  43. Open an `.appmap` from `.flutter-map/`—or any expo-map-compatible bundle—to
  44. replace the demo. Pan and zoom the graph, inspect solid code-declared and
  45. dashed agent-observed edges, follow flow playback with tap/swipe overlays,
  46. switch captured screen states, isolate one-action neighbours, jump through the
  47. minimap, and copy replay commands. Bundle contents are parsed locally in the
  48. browser and are not uploaded.
  49. ![Flutter Map visualiser showing the captured Bluesky navigation graph and an agent flow](docs/images/flutter-map-visualiser.jpg)
  50. *The bundled Bluesky map with its Home route selected, connected navigation
  51. edges, replay controls, and graph minimap.*
  52. ## Quick start
  53. ```bash
  54. cd packages/flutter_map_parser
  55. dart pub get
  56. dart test
  57. # parse + pack (static, no simulator)
  58. dart run bin/flutter_map.dart ../../fixtures/demo_go_router
  59. # parse + prepare deep-link explore stubs
  60. dart run bin/prepare_explore.dart ../../fixtures/demo_go_router
  61. ```
  62. ## Agent skill
  63. The `flutter-map` skill can run the complete mapping workflow for another
  64. Flutter project: parse its routes, prepare deep links, capture screens and
  65. runtime states on a simulator or emulator, record navigation flows, and package
  66. the result as an expo-map-compatible `.appmap` bundle.
  67. ### Install
  68. From this repository, link the skill into your agent's skill directory:
  69. ```bash
  70. # Codex
  71. mkdir -p ~/.codex/skills
  72. ln -s "$(pwd)/skills/flutter-map" ~/.codex/skills/flutter-map
  73. # Cursor
  74. ln -s "$(pwd)/skills/flutter-map" ~/.cursor/skills/flutter-map
  75. # Claude
  76. ln -s "$(pwd)/skills/flutter-map" ~/.claude/skills/flutter-map
  77. ```
  78. Start a new agent task after installation so the skill is discovered.
  79. ### Use
  80. Open the Flutter project you want to map, then ask Codex:
  81. ```text
  82. Use $flutter-map to create a full navigation map of this app.
  83. ```
  84. You can also supply a project path or limit how far the workflow runs:
  85. ```text
  86. Use $flutter-map on /path/to/my_flutter_app.
  87. Use $flutter-map --prepare on this app.
  88. Use $flutter-map --static on this app.
  89. ```
  90. | Mode | Result |
  91. |------|--------|
  92. | default | Full parse, simulator/emulator capture, flow recording, and packaging |
  93. | `--prepare` | Parse routes and write the exploration plan and deep-link flow stubs, then stop |
  94. | `--static` | Parse and package without launching a simulator; captures are marked missing |
  95. In Cursor or Claude, invoke `/flutter-map` instead.
  96. For the best full capture, boot an iOS Simulator or Android emulator first,
  97. configure a working deep-link scheme, and make safe fixture or test data
  98. available for parameterized and authenticated routes. When native devices are
  99. unavailable, the skill can use its more limited browser-capture fallback.
  100. ### Output
  101. All generated files stay inside the mapped Flutter project:
  102. ```text
  103. .flutter-map/
  104. ├── graph.json
  105. ├── explore-plan.json
  106. ├── capture-status.json
  107. ├── screens/
  108. ├── flows/
  109. ├── map.html
  110. └── <app-name>-<date>.appmap
  111. ```
  112. Open the final `.appmap` with the Flutter visualiser above, or open `map.html`
  113. for a self-contained review. Consider adding `.flutter-map/` to the target
  114. project's `.gitignore`.
  115. See [`skills/flutter-map/SKILL.md`](skills/flutter-map/SKILL.md) for the full
  116. capture procedure and safety rules.
  117. ## Replay a flow
  118. Flows are stored as runnable Argent YAML with a cartography metadata sidecar.
  119. Replay one against a running simulator or emulator with:
  120. ```bash
  121. npx @swmansion/argent flow run \
  122. .flutter-map/flows/<flow-name>.yaml
  123. ```
  124. Legacy JSON flows can be migrated once:
  125. ```bash
  126. dart run packages/flutter_map_parser/bin/convert_flows.dart \
  127. /path/to/flutter-project --delete-v1
  128. ```
  129. ## Repository layout
  130. - `skills/flutter-map/` — agent orchestration, capture phases, and safety rules
  131. - `packages/flutter_map_parser/` — route parser, explore-plan generator,
  132. renderer, flow converter, and `.appmap` packer
  133. - `apps/flutter_map_visualiser/` — Flutter web visualiser and bundled Bluesky
  134. demonstration map
  135. - `docs/appmap-format.md` — versioned `.appmap` and Argent sidecar contract
  136. - `fixtures/` — minimal apps covering every supported Flutter routing mode
  137. ## Known limitations
  138. - Static edge extraction is source-driven. Highly dynamic route construction
  139. may remain unresolved, and navigation invoked from shared widgets can be
  140. attributed to an imperfect source route.
  141. - Routes without a usable URL or deep link may require recorded in-app
  142. navigation and are marked `needsNavigation` rather than treated as directly
  143. reachable.
  144. - Authenticated, parameterized, or network-backed screens need safe fixture
  145. data for representative captures. The map records auth walls, loading
  146. screens, not-found pages, and error boundaries instead of hiding them.
  147. - Full capture requires a booted iOS Simulator or Android emulator. The browser
  148. fallback can capture web routes, but it cannot validate native navigation
  149. stacks, system gestures, or native flow replay.
  150. ## Routing modes
  151. | Mode | Detection | Fixture |
  152. |------|-----------|---------|
  153. | GoRouter | `GoRouter(` | `fixtures/demo_go_router` |
  154. | go_router_builder | `@TypedGoRoute` | `fixtures/demo_go_router_builder` |
  155. | AutoRoute | `@AutoRouterConfig` | `fixtures/demo_auto_route` |
  156. | Navigator 1.0 | `MaterialApp`/`CupertinoApp` + `routes` / `onGenerateRoute` | `fixtures/demo_navigator` |
  157. | Navigator 2.0 | `MaterialApp.router` / `RouterDelegate` + `pages:` | `fixtures/demo_navigator_2` |
  158. ## Status
  159. - [x] Imperative GoRouter parse
  160. - [x] go_router_builder TypedGoRoute parse
  161. - [x] AutoRoute parse
  162. - [x] Navigator 1.0 named routes + onGenerateRoute parse
  163. - [x] Navigator 2.0 RouterDelegate pages parse
  164. - [x] Edge + state-hint + scheme extraction
  165. - [x] Pack `.flutter-map` → v2 `.appmap`
  166. - [x] Explore prepare (deep-link flows + plan)
  167. - [x] Agent skill for live simulator/emulator sweep
  168. - [x] Flutter web `.appmap` visualiser (`apps/flutter_map_visualiser`)
  169. - [x] Observed/synthetic edges, transition trigger pinning, and state-aware playback
  170. - [x] Static self-contained `map.html` review fallback
  171. - [x] Legacy JSON → Argent flow migration

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.