FlutterSDK Dusk

Dusk

End-to-end driver for Flutter apps. Read by humans, driven by AI agents.

Snapshot the Semantics tree, drive any gesture, capture screenshots, observe live state, all from one CLI and one stdio MCP server.

Documentation · pub.dev · Issues

---

[!NOTE]

Requires Dart SDK >= 3.4.0 and Flutter >= 3.22.0. dusk is debug-only: production builds tree-shake the entire driver across web, desktop, and mobile.

Installation

flutter pub add fluttersdk_dusk

dart run fluttersdk_dusk dusk:install # patches lib/main.dart + scaffolds ./bin/fsa + registers dusk plugin

That's it. After the second command, all 41 dusk:* commands surface through ./bin/fsa (~110ms warm) or dart run fluttersdk_dusk (works the same, ~3s startup), and the MCP server is one dart run fluttersdk_dusk mcp:install away. When fastcli (./bin/fsa) is absent, mcp:install writes dart run fluttersdk_dusk mcp:serve into .mcp.json automatically; no manual edit required. See MCP install: 8 clients for the per-client wiring. Manual wiring, Magic-stack integration, and the full per-command flag reference live in the Getting Started guide.

[!TIP]

fastcli is the AOT-compiled artisan dispatcher (~110ms warm) shipped as ./bin/fsa. dusk:install scaffolds it for you automatically (best-effort; falls through to a warning when dart is not on PATH). After that, every ./bin/fsa is the fast path. The CLI also runs as dart run fluttersdk_dusk with the same surface, ~3s slower per call.

Why Dusk?

End-to-end testing on Flutter has always been a stitched-together ritual. flutter_driver ships a one-off socket protocol that does not survive hot restart. integration_test runs in-process against a simulated WidgetTester, but you write a test file, build, run, and wait. AI coding agents that want to drive the running app reach for ad hoc flutter test invocations, copy stack traces back into the prompt, and paste screenshots back, calling it a workflow.

Dusk closes that loop. A single VM Service extension family (ext.dusk.*), a single CLI namespace (dusk:*), and a single stdio MCP server back 41 CLI commands and 39 MCP tools (33 ext.dusk.* + 6 artisan:dusk:* substrate-routed). The same contracts power human-driven terminal calls and agent-driven MCP tool calls: dusk:tap --ref=e7 (CLI) and dusk_tap (MCP) reach the exact same code path. No test harness, no test file, no build step. Attach to the live app and the agent has eyes (dusk_snap, dusk_screenshot, dusk_observe) and hands (dusk_tap, dusk_type, dusk_scroll, dusk_drag). On Flutter web, the dusk:screenshot CLI command falls back to CDP Page.captureScreenshot when artisan was started with --cdp-port, bypassing the in-isolate extension that hangs under CanvasKit; the dusk_screenshot MCP tool still dispatches in-isolate, so web agents should use the CLI for screenshots. dusk_exceptions captures non-fatal FlutterErrors (including overflow) in-package so diagnostics work even without telescope.

Features

[!IMPORTANT]

DuskPlugin.install() must be wrapped in if (!kReleaseMode) { ... } at the call site in lib/main.dart, so debug and profile builds carry it (dusk:perf_run measures a profile build). An app wired under kDebugMode before this still works in debug, but registers no ext.dusk.* in a profile build. Release builds tree-shake the entire driver across web (dart2js), desktop (dart2native), and mobile (AOT), but only when the guard exists. Without the guard, dusk ships into release binaries.

AI Coding Assistants

Dusk ships AI-first. The skill at skills/fluttersdk-dusk/SKILL.md teaches your agent the 6 core laws, the e / q ref grammar, the 6-step actionability vocabulary, the 39 MCP tool surface, and the agent-workflow playbooks. The same skill is distributed through fluttersdk/ai for Claude Code, Cursor, OpenCode, Gemini CLI, VS Code Copilot, Codex CLI, Cline, and Roo Code, one command:

npx skills add fluttersdk/ai --skill fluttersdk-dusk

The hosted MCP server at mcp.fluttersdk.com exposes a search-docs tool over Streamable HTTP (no auth) for agents that need to query the dusk docs corpus directly. For stdio-only clients, the npx @fluttersdk/mcp bridge proxies stdio to the upstream HTTP server. The LLM-readable inventory lives at llms.txt. Full multi-client wire-up and the OpenCode registry URL live in the fluttersdk/ai README.

This is independent of dusk's own runtime MCP server (./bin/fsa mcp:serve, covered in the next section): the docs MCP teaches the agent ABOUT dusk; the runtime MCP gives the agent eyes and hands on a running Flutter app.

MCP install: 8 clients

Dusk is the first Flutter MCP server focused on UI automation (tap, snap, screenshot, observe) rather than runtime telemetry. The 39 dusk_* tools surface to any MCP-compatible agent.

[!NOTE]

Configs below use ./bin/fsa (the fastcli wrapper, see top of README). If fastcli is not scaffolded yet, swap ./bin/fsa mcp:serve for dart run fluttersdk_dusk mcp:serve in every client row.

Standard config (any client that reads .mcp.json in the project root):

{

"mcpServers": { "fluttersdk": { "command": "./bin/fsa", "args": ["mcp:serve"], "cwd": "." } } }

| **Claude Deskto