Redth.MauiDevFlow.Blazor.Gtk 0.23.1

MauiDevFlow

Unified tooling for automating and debugging .NET MAUI apps — both native MAUI and Blazor Hybrid. Built to enable AI agents (and humans) to build, deploy, inspect, and debug MAUI apps entirely from the terminal.

What This Is (and Isn't)

MauiDevFlow is designed for agentic development workflows — giving AI coding agents full autonomy over the MAUI dev loop: build, deploy, inspect, interact, diagnose, fix, and repeat.

It is not a UI testing framework, and it is not meant to ship in your app. The agent and debug bridge are intended for #if DEBUG only. Think of it as giving your AI pair-programmer eyes and hands inside the running app so it can close the feedback loop on its own — verify its changes work, see what went wrong when they don't, and iterate without waiting for a human to manually check the simulator.

Features

• Native MAUI Automation — Visual tree inspection, element interaction (tap, fill, clear), screenshots via in-app Agent
• Blazor WebView Debugging — CDP bridge using Chobitsu for JavaScript evaluation, DOM manipulation, page navigation. Supports multiple BlazorWebViews per app with independent targeting
• Unified Logging — Native ILogger and WebView console.log/warn/error unified into a single log stream with source filtering
• Network Request Monitoring — Automatic HTTP traffic interception via DelegatingHandler with real-time WebSocket streaming, body capture, and JSONL output
• App Storage Management — Read, write, and delete Preferences (typed key-value) and SecureStorage entries remotely
• Platform Features — Query device info, battery, connectivity, display, permissions, version tracking, geolocation, and app info
• Sensor Streaming — Start/stop device sensors (accelerometer, gyroscope, compass, barometer, magnetometer, orientation) with real-time WebSocket streaming
• Broker Daemon — Automatic port assignment and agent discovery for simultaneous multi-app debugging
• CLI Tool (maui-devflow) — Scriptable commands for both native and Blazor automation
• Driver Library — Platform-aware (Mac Catalyst, Android, iOS Simulator, Linux/GTK) orchestration
• AI Skill — Claude Code skill (.claude/skills/maui-ai-debugging) for AI-driven development workflows

Quick Start

AI-Assisted Setup (Recommended)

The fastest way to get started is to let your AI agent set everything up using the included skill:

1. Install the CLI tool and download the skill:

dotnet tool install --global Redth.MauiDevFlow.CLI
maui-devflow update-skill

2. Ask your AI agent to set up MauiDevFlow:

Use the maui-ai-debugging skill to integrate MauiDevFlow into my MAUI app. Add the NuGet packages, configure MauiProgram.cs, and set up everything needed for debugging. Then build, run, and verify it works.

The skill includes a complete setup guide with a step-by-step checklist, platform-specific configuration (entitlements, port forwarding), and the full command reference. The agent will handle NuGet packages, code changes, Blazor script tags, and verification.

Manual Setup

<details> <summary>Click to expand manual setup steps</summary>

1. Add NuGet Packages

<PackageReference Include="Redth.MauiDevFlow.Agent" Version="*" />
<PackageReference Include="Redth.MauiDevFlow.Blazor" Version="*" />  

2. Configure MauiProgram.cs

// MauiProgram.cs
using MauiDevFlow.Agent;
using MauiDevFlow.Blazor;

var builder = MauiApp.CreateBuilder();
// ... your existing setup ...

#if DEBUG
builder.Services.AddBlazorWebViewDeveloperTools();
builder.AddMauiDevFlowAgent();
builder.AddMauiBlazorDevFlowTools(); // Blazor Hybrid only
#endif

Agent options: Port (default 9223), Enabled (default true), MaxTreeDepth (0 = unlimited), EnableProfiler (default false), ProfilerSampleIntervalMs (default 500), MaxProfilerSamples (default 20000), MaxProfilerMarkers (default 20000), MaxProfilerSpans (default 20000), EnableHighLevelUiHooks (default true), EnableDetailedUiHooks (default false). Port is also configurable via .mauidevflow or -p:MauiDevFlowPort=XXXX.

With EnableProfiler=true, the agent uses native frame pipelines where available (Android FrameMetrics on API 24+, Android Choreographer fallback, Apple CADisplayLink, Windows CompositionTarget.Rendering) and emits frame/jank/stall signals (frameSource, jankFrameCount, uiThreadStallCount). Android FrameMetrics is treated as exact native timing; cadence-based providers (Apple/Windows/Android fallback) are reported with non-exact frame quality so consumers can distinguish confidence levels. High-level UI milestones (navigation/page/scroll) are enabled by default; per-control hooks are optional via EnableDetailedUiHooks=true when deep interaction traces are needed.

Blazor options: Enabled (default true), EnableWebViewInspection (default true), EnableLogging (default true in DEBUG). CDP commands are routed through the agent port — no separate Blazor port needed.

Both methods extend MauiAppBuilder.

3. Port Configuration (optional)

The CLI includes a broker daemon that automatically assigns ports to each running agent — no manual configuration needed for most workflows. Run maui-devflow list to see all connected agents and their ports.

For explicit port control (or when the broker isn't available), create a .mauidevflow in your project directory:

{ "port": 9347 }

Both the build and CLI auto-detect this file — no flags needed. See broker documentation for details.

3. Blazor Hybrid: Automatic Setup

The chobitsu.js debugging library is automatically injected via a Blazor JS initializer — no manual script tag needed. Just add the NuGet package and register in MauiProgram.cs.

Note: If auto-injection doesn't work in your setup, you can add the script tag manually in wwwroot/index.html:

<script src="chobitsu.js"></script>  

4. Install CLI Tools

dotnet tool install --global Redth.MauiDevFlow.CLI
dotnet tool install --global androidsdk.tool    # android (SDK, AVD, device management)
dotnet tool install --global appledev.tools     # apple (simulators, provisioning, certificates)

5. Platform-Specific Setup

• Mac Catalyst: Add com.apple.security.network.server entitlement (see setup guide)
• Android Emulator: Run adb reverse tcp:19223 tcp:19223 (broker) and adb forward tcp:<port> tcp:<port> (agent — get port from maui-devflow list)
• iOS Simulator: No extra setup needed
• Linux/GTK: No extra setup needed (see Linux guide)

</details>

Verify It Works

# Wait for an agent to connect (blocks until ready)
maui-devflow wait

# List all connected agents (via broker)
maui-devflow list

# Check agent connection
maui-devflow MAUI status

# Dump visual tree (all windows)
maui-devflow MAUI tree

# Dump visual tree for a specific window (0-based index)
maui-devflow MAUI tree --window 1

# Take screenshot
maui-devflow MAUI screenshot --output screen.png

# Take screenshot of a specific element
maui-devflow MAUI screenshot --id HeaderLabel --output header.png
maui-devflow MAUI screenshot --selector "Button" --output button.png

# Fetch application logs
maui-devflow MAUI logs --limit 50

# Filter by source (native ILogger or Blazor WebView console)
maui-devflow MAUI logs --source webview
maui-devflow MAUI logs --source native

# Screen recording (start/stop)
maui-devflow MAUI recording start --timeout 30
# ... interact with the app ...
maui-devflow MAUI recording stop

# Network request monitoring
maui-devflow MAUI network              # live monitor (Ctrl+C to stop)
maui-devflow MAUI network --json       # JSONL streaming for AI
maui-devflow MAUI network list         # one-shot dump of recent requests
maui-devflow MAUI network detail <id>  # full headers + body for a request
maui-devflow MAUI network clear        # clear captured requests

# App storage
maui-devflow MAUI preferences list               # list known keys
maui-devflow MAUI preferences get theme_mode      # get a value
maui-devflow MAUI preferences set api_url "https://dev.example.com"
maui-devflow MAUI secure-storage get auth_token   # encrypted storage

# Platform info & sensors
maui-devflow MAUI platform app-info               # app name, version, theme
maui-devflow MAUI platform device-info            # manufacturer, model, OS
maui-devflow MAUI platform battery                # charge level, state
maui-devflow MAUI platform connectivity           # network access, profiles
maui-devflow MAUI platform permissions            # check all permission statuses
maui-devflow MAUI platform geolocation            # GPS coordinates
maui-devflow MAUI sensors list                    # list sensors + status
maui-devflow MAUI sensors stream accelerometer    # live WebSocket stream

# Live edit native properties (no rebuild)
maui-devflow MAUI set-property HeaderLabel TextColor "Tomato"
maui-devflow MAUI set-property HeaderLabel FontSize "32"

# Blazor WebView (if applicable)
maui-devflow cdp status
maui-devflow cdp snapshot

Blazor WebView CDP Commands

For Blazor Hybrid apps with the CDP bridge configured:

# Check CDP connection and WebView count
maui-devflow cdp status

# List all registered WebViews (useful when app has multiple BlazorWebViews)
maui-devflow cdp webviews
maui-devflow cdp webviews --json

# Page snapshot (useful for AI agents — accessible text representation of DOM)
maui-devflow cdp snapshot

# Evaluate JavaScript
maui-devflow cdp Runtime evaluate "document.title"

# DOM queries
maui-devflow cdp DOM querySelector "button.btn-primary"
maui-devflow cdp DOM querySelectorAll "a.nav-link"
maui-devflow cdp DOM getOuterHTML "div.container"

# Input actions
maui-devflow cdp Input dispatchClickEvent "button"
maui-devflow cdp Input fill "input#name" "John"
maui-devflow cdp Input insertText "typed text"

# Page navigation
maui-devflow cdp Page navigate "https://example.com"
maui-devflow cdp Page reload
maui-devflow cdp Page captureScreenshot

# Get full page HTML source
maui-devflow cdp source
maui-devflow cdp source --webview BlazorLeft

# Live CSS/DOM editing (experiment without rebuilding)
maui-devflow cdp Runtime evaluate "document.querySelector('h1').style.color = 'tomato'"
maui-devflow cdp Runtime evaluate "document.querySelectorAll('.item').forEach(el => el.style.borderRadius = '20px')"
maui-devflow cdp Runtime evaluate "document.documentElement.style.setProperty('--bg-color', '#1a1a2e')"
maui-devflow cdp Runtime evaluate "document.head.insertAdjacentHTML('beforeend', '<style>.btn { background: hotpink !important; }</style>')"

Multi-WebView Targeting

Apps with multiple BlazorWebView controls (e.g. side-by-side views, split layouts) are fully supported. Each WebView registers independently with the agent using its AutomationId.

# List all WebViews — shows index, AutomationId, and ready status
maui-devflow cdp webviews

# Target a specific WebView by AutomationId
maui-devflow cdp --webview BlazorLeft snapshot
maui-devflow cdp -w BlazorRight Runtime evaluate "document.title"

# Target by index (0-based)
maui-devflow cdp -w 0 Runtime evaluate "1+1"
maui-devflow cdp -w 1 DOM querySelector "h1"

Without --webview, all CDP commands target the first registered WebView (index 0). The --webview (-w) option is available on every cdp subcommand.

Tip: Live CSS/DOM edits are immediate and non-destructive — changes are lost on page reload, making them safe for experimentation before committing to code.

Note: On iOS/Mac Catalyst, Page.reload, Page.navigate, and Input.insertText are intercepted and handled via native WKWebView APIs. This is necessary because these operations destroy/recreate the JavaScript context — the Chobitsu debug bridge is automatically re-injected after reload/navigation completes.

Agent API

The Agent runs inside the MAUI app and exposes an HTTP/JSON REST API. The port is auto-assigned by the broker (range 10223–10899), or configurable via .mauidevflow / --agent-port.

Platform endpoints return structured JSON errors on failure. In addition to success and error, failures may include a machine-readable reason and details object so clients can distinguish cases like missing_permission, not_supported, main_thread_required, timeout, and unknown without parsing the error text. | /api/sensors | GET | List all sensors with support/active/subscriber status | | /api/sensors/{sensor}/start | POST | Start sensor. ?speed=UI\|Game\|Fastest\|Default | | /api/sensors/{sensor}/stop | POST | Stop sensor | | /ws/sensors | WS | Stream sensor readings. ?sensor=accelerometer ?speed=UI | | /api/cdp | POST | Forward CDP command to Blazor WebView. Use ?webview=<id> to target a specific WebView | | /api/cdp/webviews | GET | List registered CDP WebViews (index, AutomationId, elementId, ready status) | | /api/cdp/source | GET | Get page HTML source. Use ?webview=<id> to target a specific WebView | | /api/profiler/capabilities | GET | Profiling capability matrix and availability (EnableProfiler) | | /api/profiler/start | POST | Start profiling session. Optional body: {"sampleIntervalMs":500} | | /api/profiler/stop | POST | Stop active profiling session | | /api/profiler/samples?sampleCursor=S&markerCursor=M&spanCursor=P&limit=N | GET | Poll sample + marker + span batch since cursors | | /api/profiler/marker | POST | Publish manual marker {"type":"user.action","name":"...","payloadJson":"..."} | | /api/profiler/span | POST | Publish manual span {"kind":"ui.operation","name":"...","startTsUtc":"...","endTsUtc":"..."} | | /api/profiler/hotspots?kind=ui.operation&minDurationMs=16&limit=20 | GET | Aggregated slow-operation hotspots ordered by P95 duration |

Profiler sample payloads also include nativeMemoryKind to disambiguate what nativeMemoryBytes means for that sample. Current values include apple.phys-footprint, android.native-heap-allocated, windows.working-set, and process.working-set-minus-managed when the collector falls back to process working set minus managed memory.

Project Structure

MauiDevFlow.sln
.claude/skills/
└── maui-ai-debugging/          # AI skill for Claude Code
src/
├── MauiDevFlow.Agent/          # In-app agent (NuGet library for MAUI apps)
├── MauiDevFlow.Agent.Core/     # Platform-agnostic agent core (shared by Agent & Agent.Gtk)
├── MauiDevFlow.Agent.Gtk/      # GTK/Linux agent (NuGet library for Maui.Gtk apps)
├── MauiDevFlow.Blazor/         # Blazor WebView CDP bridge (Chobitsu)
├── MauiDevFlow.Blazor.Gtk/     # Blazor CDP bridge for WebKitGTK on Linux
├── MauiDevFlow.CLI/            # CLI tool (maui-devflow)
├── MauiDevFlow.Driver/         # Driver library (connects to Agent, platform tools)
└── SampleMauiApp/              # Sample todo app (native + Blazor Hybrid via Shell)
tests/
├── MauiDevFlow.Console/        # Console test app for CDP
└── MauiDevFlow.Tests/          # Unit and integration tests
docs/
├── broker.md                   # Broker daemon architecture and API
└── setup-guides/               # Platform-specific setup (Android, Apple, Windows)

Sample App

The SampleMauiApp is a shared-state todo list with both a native MAUI page and a Blazor Hybrid page, connected via Shell navigation (//native and //blazor routes). It demonstrates:

• Shared TodoService — both pages read/write the same data, changes reflect immediately
• Shell navigation — switch between tabs via maui-devflow MAUI navigate "//native" etc.
• Dark mode support — both native (AppThemeBinding) and Blazor (@media prefers-color-scheme) adapt to system theme
• Description field — todo items support title + optional description on both pages
• Multi-WebView — the //multiblazor route shows two side-by-side BlazorWebViews (BlazorLeft and BlazorRight) for testing multi-WebView CDP targeting

Platform Support

Companion Tools

AI Agent Integration

This project includes a Claude Code skill (.claude/skills/maui-ai-debugging) that teaches AI agents the complete build → deploy → inspect → fix feedback loop. The skill covers:

• Installing and configuring all required tools
• Building and deploying to iOS simulators, Android emulators, Mac Catalyst, and Linux/GTK
• Using maui-devflow to inspect visual trees, interact with elements, and take screenshots
• Using CDP to inspect and manipulate Blazor WebView content
• Automatic port discovery via the broker daemon for multi-app workflows
• Managing simulators/emulators with apple, android, xcrun simctl, and adb

Installing the Skill

The CLI can download the latest skill files directly from GitHub into your project:

# Interactive — shows files and asks for confirmation
maui-devflow update-skill

# Skip confirmation
maui-devflow update-skill -y

# Download to a specific directory
maui-devflow update-skill -o /path/to/my-project

# Use a different branch
maui-devflow update-skill -b dev

This downloads the skill files into .claude/skills/maui-ai-debugging/ relative to the output directory (or current directory if --output is not specified). Existing files are overwritten. The file list is discovered dynamically from the repository, so new reference docs are picked up automatically.

MCP Server

MauiDevFlow includes an MCP (Model Context Protocol) server for integration with AI coding agents in VS Code Copilot Chat, Claude Desktop, and other MCP-compatible hosts. The MCP server returns structured JSON and inline images — enabling AI agents to see screenshots directly and query the visual tree without text parsing.

Configuration

Add to your VS Code MCP settings (.vscode/mcp.json):

{
  "servers": {
    "maui-devflow": {
      "command": "maui-devflow",
      "args": ["mcp-serve"],
      "transportType": "stdio"
    }
  }
}

Available Tools

All tools accept an optional agentPort parameter. When omitted, the server auto-discovers the connected agent via the broker — same as the CLI.

License

MIT