Installation

• Requirements
• Add the package
• Wire DuskPlugin
• Optional integrations
• Wire MCP tools
• Verify installation

Getting fluttersdk_dusk running requires adding the package, calling DuskPlugin.install() inside a kDebugMode guard in your app's main.dart, and (optionally) wiring the MCP server so your AI client can reach the dusk tools.

Requirements

fluttersdk_dusk is a Flutter package. It requires a Flutter app target for the VM Service extensions to register against. Pure-Dart environments are not supported.

Install fluttersdk_artisan first if it is not already in your project. It provides the MCP server, the CLI framework, and the registerExtensionIdempotent helper that dusk uses internally for hot-restart safety.

dart pub add fluttersdk_artisan

Add the package

Add fluttersdk_dusk using the Flutter CLI:

flutter pub add fluttersdk_dusk

Alternatively, add it manually to pubspec.yaml:

dependencies:
  fluttersdk_dusk: ^0.0.1

Then fetch dependencies:

flutter pub get

Wire DuskPlugin

The recommended path is the CLI installer. From your project root, run:

dart run fluttersdk_dusk dusk:install

This patches your lib/main.dart automatically: it adds the kDebugMode import, wraps DuskPlugin.install() in a kDebugMode guard, injects WidgetsFlutterBinding.ensureInitialized() when missing, and detects Magic-stack apps so MagicDuskIntegration.install() lands AFTER Magic.init(...). The command is idempotent; re-running it is safe. See dusk:install for the full sub-step list and the anchor strings the injector searches for.

Manual wiring (when you'd rather edit main.dart yourself)

Skip the CLI installer and edit lib/main.dart directly. Call DuskPlugin.install() inside a kDebugMode guard, after WidgetsFlutterBinding.ensureInitialized() and before runApp(). The guard is mandatory: release builds tree-shake the entire subsystem, so dusk never ships to end users.

import 'package:flutter/foundation.dart';
import 'package:fluttersdk_dusk/dusk.dart';

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

  if (kDebugMode) {
    DuskPlugin.install();
  }

  runApp(const MyApp());
}

DuskPlugin.install() is idempotent: calling it more than once (for example during hot restart) is safe and registers each VM Service extension only once.

Optional integrations

Call additional install() methods inside the same kDebugMode block to enrich snapshots with framework-specific metadata. Both integrations are independent; install either, both, or neither depending on your stack.

if (kDebugMode) {
  DuskPlugin.install();
  MagicDuskIntegration.install(); // magic-stack only
  Wind.installDebugResolver();    // wind UI only (alpha-10+)
}

See Magic integration and Wind integration for the full enricher field reference.

Register with artisan (automatic)

dusk:install already handles this for you as Phase 2 of its run. Right after the lib/main.dart patch lands, it chains dart run fluttersdk_artisan install (scaffolds bin/dispatcher.dart + ./bin/fsa fastcli, ~110ms warm AOT) followed by dart run fluttersdk_artisan plugin:install fluttersdk_dusk (registers DuskArtisanProvider and auto-purges the AOT bundle cache). Both sub-process calls skip when their idempotency markers already exist (bin/dispatcher.dart and .artisan/installed/fluttersdk_dusk.json respectively), so re-running dusk:install is a fast no-op.

If the chained calls fail (no dart on PATH, partial pub-cache, restricted sandbox), dusk:install falls through with a warning and exits 0; the lib/main.dart patch already landed, so dart run fluttersdk_dusk still works. You can finish the setup manually:

dart run fluttersdk_artisan install                          # only if Phase 2 was skipped
dart run fluttersdk_artisan plugin:install fluttersdk_dusk   # idempotent; refreshes barrels on re-run

After Phase 2 lands, ./bin/fsa list shows all dusk:* commands and ./bin/fsa mcp:serve exposes the 31 dusk_* tools.

Wire MCP tools

With artisan registered, expose dusk's 31 MCP tools to your AI client by writing the .mcp.json entry:

dart run fluttersdk_artisan mcp:install

This writes (or updates) a .mcp.json file at the project root wiring dart run fluttersdk_artisan mcp:serve as the MCP server entry point. Claude Code, Cursor, and Windsurf all pick up .mcp.json automatically from the working directory.

If your project uses the ./bin/fsa AOT binary (shipped by the artisan scaffold), the MCP server is available without the dart run startup overhead:

./bin/fsa mcp:serve

Verify installation

Start your Flutter app in debug mode on a device or browser:

flutter run -d chrome

Then, in a separate terminal, capture the first Semantics snapshot:

dart run fluttersdk_artisan dusk:snap

A successful snap prints a YAML block beginning with snapshot: followed by one or more indented widget nodes. Each node carries a ref: token (e1, e2, ...) that you pass to action commands. If the command exits with an error, confirm that DuskPlugin.install() is reachable in your main.dart and that the app is running in debug mode (VM Service extensions do not register in profile or release builds).