Manual setup — Flutter

Prerequisites

An existing Flutter app with Dart SDK 3.0 or newer.
The Ailoha CLI installed: see install instructions.

1. Add the package

Add ailoha_agent to your app dependencies and keep startup behind kDebugMode so it never runs in release builds:

flutter pub add ailoha_agent

Or in pubspec.yaml:

dependencies:
  ailoha_agent: ^0.1.0

2. Initialize the agent

Initialize the agent early in main(), gated by kDebugMode so it doesn't run in profile or release builds:

import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:ailoha_agent/ailoha_agent.dart';

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

  if (kDebugMode) {
    await initAgent();
  }

  runApp(const MyApp());
}

3. Configure (optional)

initAgent accepts an AgentOptions instance:

await initAgent(AgentOptions(
  port: 9233,
  enableNetworkCapture: true,
  enableLogCapture: true,
));

Option	Default	Notes
`port`	`9233`	Falls back through `9238` if taken.
`enableBrokerRegistration`	`true`	Registers with the local broker on `19323`.
`enableNetworkCapture`	`true`	Wraps the default `HttpClient` for traffic capture.
`enableLogCapture`	`true`	Captures `print` and `debugPrint` output.

4. Use stable widget keys

The agent resolves widgets by their ValueKey<String>. Add keys to anything you want to query or interact with:

ElevatedButton(
  key: const ValueKey('login-button'),
  onPressed: _signIn,
  child: const Text('Sign in'),
)

The CSS-style selector engine treats ValueKey as the element ID, so #login-button just works in queries and actions.

5. Run and verify

Run flutter run, then from your dev machine:

ailoha agent status
ailoha ui tree --depth 2
ailoha ui screenshot --output ./shot.png

For Android emulators or devices, forward the port if discovery doesn't pick it up:

adb forward tcp:9233 tcp:9233

Troubleshooting

Web target. The pure-Dart HTTP server runs on platforms with dart:io. Web isn't supported by the embedded server today.
Hot restart. The agent rebinds on hot restart; no manual cleanup needed. If a port leak occurs, fully stop the app to release it.
Release build sneaks in. Confirm the initAgent call is inside if (kDebugMode) or an assert block.

What's next

See the protocol capabilities available from the CLI.
Add a custom extension from your own Flutter package.