marionette-flutter-setup

marionette_flutter: set up an app

Marionette has two halves: marionette_flutter, the package in the app, which registers a VM service extension per action (ext.flutter.marionette.*), and the bridge the agent calls, marionette_mcp (MCP tools) or marionette_cli (shell commands). This skill prepares the app for either bridge and keeps the versions aligned. Driving the app is the job of marionette-flutter-drive-app.

Add the binding

connect (or any CLI command) only works if the target app initialized MarionetteBinding. Check main.dart (or ask) before changing anything — if the binding is already there and the agent can see the app's widgets, the app is ready.

flutter pub add marionette_flutter

void main() {
  if (kDebugMode) {
    MarionetteBinding.ensureInitialized();
  } else {
    WidgetsFlutterBinding.ensureInitialized();
  }
  runApp(const MyApp());
}

This is all a standard Material-widgets app needs. It runs inside main(), so any time you add or change it, hot restart — a hot reload doesn't re-execute main(), so the change will look like it did nothing. Gate every piece of Marionette wiring behind kDebugMode (or !kReleaseMode — see Device-config sweeps, below) so none of it ships in a release build: both are compile-time constants the release branch survives cleanly.

Custom design system? Teach Marionette about it

Zero-config setup only recognizes stock Material widgets (ElevatedButton, TextField, Switch, …) and extracts text only from Text, RichText, EditableText, TextField, and TextFormField. If the app wraps its own buttons, fields, or text — true of most production apps — get_interactive_elements will look sparse and tap(text: ...) will fail to find things that are clearly on screen. That's not a Marionette bug; it just doesn't know your widgets yet:

MarionetteConfiguration(
  // Recognize your custom interactive widgets.
  isInteractiveElement: (element) => switch (element.widget) {
    MyButton() || MyTextField() => true,
    _ => false,
  },
  // Extract their visible text for text-based matching and discovery.
  extractText: (element) {
    final widget = element.widget;
    if (widget is MyText) return widget.data;
    return null;
  },
)