Skip to main content
This page takes you from “CLI installed” to “/roveflow --only=cold-setup passes on your own Flutter app” in minutes.
Build the flutter_inspector_mcp binary first if you have not already. See Build flutter_inspector_mcp.
1

Install the CLI

import Install from “/snippets/install.mdx”;See Installation for prerequisites and PATH tips.
2

Initialize into your Flutter project

From the project root:
cd my_flutter_app
roveflow init
This writes the skill, slash command, agent, lib/core/mcp/mcp_interaction_tools.dart, .mcp.json, and a starter docs/roveflow/scenarios.md. The command fails fast if the target directory is not a Flutter project.See roveflow init reference for the full list of created files and flags.
3

Add mcp_toolkit to pubspec

flutter pub add mcp_toolkit
mcp_toolkit is the only runtime dependency the interaction tools pull in.
4

Add the navigate.pop() helper

lib/core/mcp/mcp_interaction_tools.dart (written by roveflow init) imports a top-level navigate.pop() helper. Create it:
// lib/core/general_helpers/utils/navigation_util.dart
import 'package:flutter/widgets.dart';

final rootNavigatorKey = GlobalKey<NavigatorState>();

class _Navigate {
  void pop() => rootNavigatorKey.currentState?.pop();
}

final navigate = _Navigate();
If your project already exposes a navigate.pop() helper elsewhere, point the import at the top of mcp_interaction_tools.dart at that file instead of adding this one.
5

Wire main.dart

Add three imports and a debug-only registration block:
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:mcp_toolkit/mcp_toolkit.dart';
import 'package:<your_app>/core/general_helpers/utils/navigation_util.dart';
import 'package:<your_app>/core/mcp/mcp_interaction_tools.dart';

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

  if (kDebugMode) {
    MCPToolkitBinding.instance
      ..initialize()
      ..initializeFlutterToolkit();
    await registerMcpInteractionTools();
  }

  runApp(const MyApp());
}
Attach rootNavigatorKey to your MaterialApp:
MaterialApp(
  navigatorKey: rootNavigatorKey,
  // ...
)
Replace <your_app> with your pubspec name. Full context: Integrate into an existing app.
6

Verify .mcp.json

roveflow init writes .mcp.json using env-var substitution so the binary path stays out of your repo:
{
  "mcpServers": {
    "flutter-inspector": {
      "command": "${ROVEFLOW_FLUTTER_INSPECTOR}",
      "args": ["--dart-vm-port=8181", "--resources", "--images"]
    }
  }
}
Make sure ROVEFLOW_FLUTTER_INSPECTOR is exported in your shell (see Build flutter_inspector_mcp). If you prefer not to use an env var, replace the command field with the absolute path to the binary.
Port collisions. The default --dart-vm-port=8181 matches flutter run --vm-service-port=8181. If another Flutter app is already using 8181, pick an unused port (e.g., 8182) and update both .mcp.json and the flutter run command below.
7

Fill in docs/roveflow/scenarios.md

Open the file and replace the cold-setup placeholder with your app’s first-run flow. You need real screen titles for waypoints.Minimal example (from the counter app):
id: cold-setup
criticality: critical
order: 0
goal: Reach the default Flutter counter screen from cold install.
entry: cold-install
waypoints:
  - reach_screen: "Flutter Demo Home Page"
steps_hint: |
  The default Flutter app opens directly to the counter. No login.
pass: counter "0" visible AND floating-action-button visible
fail: screen blank, app crashes within 10s, or app bar title missing
Full field reference: Scenario schema.
8

Boot the app in debug mode

flutter run -d <simulator-id>
Keep it running. The agent connects to the live process via flutter-inspector MCP.
The /roveflow orchestrator will restart the app itself during its preflight (shut down, erase, boot, relaunch) so you can also skip this step and let the slash command handle it.
9

Run the smoke test in Claude Code

Open a Claude Code session with its working directory set to the Flutter project root so .mcp.json loads and flutter-inspector is available:
claude .
Then invoke:
/roveflow --only=cold-setup
The orchestrator dispatches a roveflow-runner agent, collects the structured result, and writes a session recording at docs/roveflow/runs/<timestamp>/.
If cold-setup passes, your install is good. Add more scenarios incrementally.

​
If cold-setup fails

  • Waypoint titles don’t match — screenshot your running app and copy the exact AppBar title string into waypoints.reach_screen.
  • The agent can’t find a button — either rewrite the steps_hint with clearer landmarks, or add a ValueKey (see Using ValueKeys).
  • App won’t boot — check /tmp/flutter-smoke-run.log for build errors.
  • Port already in use: another Flutter process is holding 8181. Stop it or pick a different port in .mcp.json + flutter run --vm-service-port=.
  • Using fvm or a flavor: the skill auto-detects fvm from .fvmrc/.fvm/. For flavors or custom wrappers, drop a docs/roveflow/config.yaml (see run config reference).

​
Next

Authoring scenarios

YAML format, criticality tiers, and skip results.

Running smoke tests

Modes, flags, and reporting.

CLI reference

Every command and flag on one page.

Counter app walkthrough

The dogfood install in full.