flutterctl

Programmatic Flutter development control for AI agents, CI pipelines, and automation.

When working with AI coding assistants (Claude Code, Cursor, Copilot), the AI cannot interact with flutter run's interactive terminal. flutterctl wraps Flutter's daemon protocol and VM service to expose everything as simple CLI commands — and as an MCP server for direct AI agent integration. Zero app modification required.

Installation

pub.dev (recommended for Flutter developers):

dart pub global activate flutterctl

Homebrew:

brew install flutterctl/tap/flutterctl

Direct binary (GitHub Releases): Download from Releases.

Quick Start

# Start Flutter on a device
flutterctl start -d emulator-5554

# Check status (waits for app to boot)
flutterctl status

# Hot reload after code changes
flutterctl reload

# Inspect the running app
flutterctl inspect widgets
flutterctl inspect memory
flutterctl inspect errors

# Take a screenshot
flutterctl screenshot --out screen.png

# View logs
flutterctl logs --follow

# Stop everything
flutterctl stop

All Commands

Lifecycle

Command	Description
flutterctl start [flags]	Launch Flutter. Accepts all flutter run flags: --device/-d, --flavor, --dart-define
flutterctl stop	Stop the Flutter app and manager
flutterctl reload	Hot reload — preserves app state
flutterctl restart	Full hot restart — resets app state
flutterctl status	Manager state, device, uptime, VM connection
flutterctl devtools	Launch Flutter DevTools in browser

Inspection

Command	What it returns
flutterctl inspect widgets	Full widget tree as JSON
flutterctl inspect memory	Heap usage, capacity, allocation profile
flutterctl inspect cpu	CPU sample count, period, stack depth
flutterctl inspect performance	Frame timing, jank frames, timeline
flutterctl inspect errors	Recent errors and exceptions from logs
flutterctl inspect eval "<expr>"	Evaluate Dart in the running isolate

Logs & Screenshot

Command	Description
flutterctl logs [--follow] [--lines N]	Print buffered logs; --follow streams live
flutterctl screenshot [--out path]	Capture screenshot, saves as PNG

MCP Server

flutterctl mcp-server

Starts a stdio MCP server. Add to your AI client config:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "flutterctl": {
      "command": "flutterctl",
      "args": ["mcp-server"]
    }
  }
}

Cursor (.cursor/mcp.json in project root):

{
  "mcpServers": {
    "flutterctl": {
      "command": "flutterctl",
      "args": ["mcp-server"]
    }
  }
}

MCP tools exposed: flutter_start, flutter_stop, flutter_reload, flutter_restart, flutter_status, flutter_logs, flutter_screenshot, flutter_devtools, flutter_inspect_widgets, flutter_inspect_memory, flutter_inspect_cpu, flutter_inspect_performance, flutter_inspect_errors, flutter_inspect_eval

JSON Output

Every command supports --json / -j for machine-readable output:

flutterctl reload --json
# {"success":true,"message":"Hot reload complete (342ms).","data":{"reloadMs":342}}

flutterctl inspect memory --json
# {"heapUsage":12345678,"heapCapacity":20971520,"externalUsage":1234,"memberCount":891}

Exit Codes

Code	Meaning
0	Success
1	Flutter error (compile error, app crash)
2	Manager not running
3	Timeout

vs. marionette_mcp / mcp_flutter

Both require modifying your Flutter app. flutterctl does not — it works on any project immediately. The trade-off: those tools support UI interaction (tap, type, scroll) via custom in-app extensions. flutterctl v2 plans to add coordinate-based UI interaction via ADB/xcrun.

Architecture

flutterctl start
      │
      ▼
Manager Process (background)
      ├── flutter run --machine ──► Flutter daemon JSON-RPC
      ├── DDS WebSocket ──────────► vm_service (widget tree, memory, CPU, etc.)
      └── Unix socket ────────────► client commands (reload, inspect, logs...)
                                     └── MCP server (Claude Desktop, Cursor)

Requirements

• Dart SDK 3.4+ (comes with Flutter)
• Flutter SDK in PATH
• macOS or Linux (Windows planned for v2)

Contributing

Issues and PRs welcome at github.com/williamomeara/flutterctl.

License

MIT