Flutter 3.50 shipped official agent plugins, and one of their rules hot reloads the app every time the agent edits a file under lib/. That's good. But a reload only says the code compiled. It doesn't say the button works, or that the header still fits on a phone.
My loop used to be: hot reload, take a screenshot, drag the PNG into the chat, paste the widget source, ask why the button does nothing. Today, I'll show you how I let the agent do that part itself.
TL;DR: Tapir runs inside your debug build and gives your agent an MCP server: a Semantics snapshot with a ref for every control, real taps and typing, an effect block that says whether it worked, and the errors the app raised. Shrink the web view to iPhone width and the agent finds the layout bugs a desktop window hides.
flutter pub add tapir dowel
dart run tapir tapir:install
dart run tapir mcp:install
tapir:install patches main.dart and puts TapirPlugin.install() behind !kReleaseMode, so a release build carries none of it:
mcp:install writes a dowel entry into .mcp.json (./bin/dowel mcp:serve). In Claude Code run /mcp reconnect dowel once; Cursor, VS Code, Windsurf and Codex read the same entry. The server answered my tool list request with 40 tapir_* tools.
Then start the app through Tapir, so every command finds the session:
dart run tapir start --device=chrome --cdp-port=9333
A snapshot is the first call. Here is the same thing from the terminal:
- button "Need help?" [ref=e1]
- textbox "Email" [ref=e2]
typeable: true
- textbox "Password" [ref=e3]
typeable: true
- button "Sign in" [ref=e4]
It's a guest list at the door instead of a photo of the crowd. No pixel guessing; every control has a ref the agent can act on, and five lines cost almost nothing in context.
./bin/dowel tapir:fill --ref=e2 --text="ada"
./bin/dowel tapir:fill --ref=e3 --text="short"
./bin/dowel tapir:tap --ref=e4
./bin/dowel tapir:snap --grep="Enter|Use at"
✓ Tapped e4 (target unchanged)
- textbox "Email": "ada" [ref=e2]
- text "Enter a valid email."
- textbox "Password": "•••••" [ref=e3]
- text "Use at least 8 characters."
A green tick only says the event left Tapir, so the agent reads effect (with --json). With valid values the tap on "Sign in" answered {"changed": false, "routeChanged": true}: the button didn't change, but a new page opened. And a tap on something covered is refused with a reason the agent can act on:
Widget ref=e4 is not actionable: obscured by other widget (top=_RenderInkFeatures)
At desktop width, tapir:exceptions was empty. Then I gave the page iPhone 15 Pro's width:
./bin/dowel tapir:resize_viewport --width=393 --height=852 --dpr=2.0 --mobile --touch --hold
The next snapshot:
✗ ⚠ 1 render error(s) captured on this screen (run tapir:exceptions / tapir_exceptions for full detail):
✗ - overflow: A RenderFlex overflowed by 67 pixels on the right.
- button "Need help?" [ref=e1]
overflow: true
The title and the help link sit in a Row, and the title has no room to wrap. One Expanded fixes it, and tapir:hot_reload_and_snap confirms it in one round trip:
integration_test or Patrol in CI. The official Dart and Flutter MCP server has a Flutter Driver tool that can turn a user journey into a driver test, if a test file is what you want.--cdp-port session runs on the web-server device, which can't evaluate Dart expressions.
How do you check your agent's UI changes today: screenshots in the chat, a test suite, or by hand?
The full walkthrough, with the dark theme file and the notes on tapir:exceptions --since, is on my blog: Let your AI agent test your Flutter app with Tapir.