Manual setup — WinUI 3

Prerequisites

A WinUI 3 (Windows App SDK) project on .NET 10.
The Ailoha CLI installed: see install instructions.

1. Install the package

dotnet add package Ailoha.Agent.WinUI

Or in your .csproj:

<PackageReference Include="Ailoha.Agent.WinUI" Version="0.1.*" />

2. Start the agent

Start the agent from your main window once it's activated. Wrap the call in #if DEBUG so it doesn't ship in release builds:

using Ailoha.Agent.WinUI;

public sealed partial class MainWindow : Window
{
    private WinUiDevFlowAgent? _agent;

    public MainWindow()
    {
        this.InitializeComponent();

#if DEBUG
        _agent = WinUiDevFlowAgent.Start(this, options =>
        {
            options.Port = 9233;
            options.AppName = "My WinUI App";
        });
#endif
    }
}

3. Configure (optional)

Option	Default	Notes
`Port`	`9233`	Override with the `AILOHA_PORT` env var when launching multiple local fixtures.
`EnableBrokerRegistration`	`true`	Registers with the broker on `19323` for CLI discovery.
`RouteResolver`	`null`	Maps protocol route names to your app's navigation. Lets `/ui/actions/navigate` work without a custom extension.
`BackHandler`	`null`	Hook for the protocol back action.
`WindowsProvider`	`null`	Returns extra `Window` instances for multi-window apps.

Wiring up route-based navigation

_agent = WinUiDevFlowAgent.Start(this, options =>
{
    options.RouteResolver = route =>
    {
        switch (route)
        {
            case "home":     RootFrame.Navigate(typeof(HomePage)); return true;
            case "settings": RootFrame.Navigate(typeof(SettingsPage)); return true;
            default:         return false;
        }
    };
    options.BackHandler = () => { if (RootFrame.CanGoBack) { RootFrame.GoBack(); return true; } return false; };
});

4. Use stable element IDs

The agent prefers AutomationProperties.AutomationId, then FrameworkElement.Name, then a generated visual-tree path. Set AutomationId on anything you want to query reliably:

<Button x:Name="LoginButton"
        AutomationProperties.AutomationId="login-button"
        Click="OnLoginClicked">Sign in</Button>

5. Run and verify

dotnet build winui\agent\Ailoha.Agent.WinUI\Ailoha.Agent.WinUI.csproj
ailoha agent status
ailoha ui tree --depth 2

Troubleshooting

Unsupported APIs. Some Windows APIs (secure storage, certain identity-sensitive surfaces) require packaged identity. The agent reports these as unsupported until they're implemented.
WebView2 screenshots. The agent uses CoreWebView2.CapturePreviewAsync. Make sure the WebView2 runtime is installed on the target machine.
Multi-window apps. Set options.WindowsProvider to expose all your windows so the visual tree includes them.

What's next

Browse the protocol capabilities the CLI and MCP can call.
Add a custom extension from your own WinUI library.