{"id":43902394,"url":"https://github.com/redth/mauidevflow","last_synced_at":"2026-03-09T01:03:51.100Z","repository":{"id":336895099,"uuid":"1151006937","full_name":"Redth/MauiDevFlow","owner":"Redth","description":"Agentic Dev Loop Assists for .NET MAUI apps","archived":false,"fork":false,"pushed_at":"2026-02-11T19:58:43.000Z","size":528,"stargazers_count":11,"open_issues_count":3,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-12T03:50:14.975Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Redth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-06T00:08:11.000Z","updated_at":"2026-02-12T00:41:10.000Z","dependencies_parsed_at":"2026-02-12T22:00:40.048Z","dependency_job_id":null,"html_url":"https://github.com/Redth/MauiDevFlow","commit_stats":null,"previous_names":["redth/mauidevflow"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/Redth/MauiDevFlow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Redth%2FMauiDevFlow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Redth%2FMauiDevFlow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Redth%2FMauiDevFlow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Redth%2FMauiDevFlow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Redth","download_url":"https://codeload.github.com/Redth/MauiDevFlow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Redth%2FMauiDevFlow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29382867,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T20:34:40.886Z","status":"ssl_error","status_checked_at":"2026-02-12T20:23:00.490Z","response_time":55,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-06T19:02:42.142Z","updated_at":"2026-03-04T00:28:46.152Z","avatar_url":"https://github.com/Redth.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MauiDevFlow\n\nUnified tooling for automating and debugging .NET MAUI apps — both native MAUI and Blazor Hybrid.\nBuilt to enable AI agents (and humans) to build, deploy, inspect, and debug MAUI apps entirely\nfrom the terminal.\n\n## What This Is (and Isn't)\n\nMauiDevFlow is designed for **agentic development workflows** — giving AI coding agents full\nautonomy over the MAUI dev loop: build, deploy, inspect, interact, diagnose, fix, and repeat.\n\nIt is **not** a UI testing framework, and it is **not** meant to ship in your app. The agent and\ndebug bridge are intended for `#if DEBUG` only. Think of it as giving your AI pair-programmer\neyes and hands inside the running app so it can close the feedback loop on its own — verify its\nchanges work, see what went wrong when they don't, and iterate without waiting for a human to\nmanually check the simulator.\n\n## Features\n\n- **Native MAUI Automation** — Visual tree inspection, element interaction (tap, fill, clear), screenshots via in-app Agent\n- **Blazor WebView Debugging** — CDP bridge using Chobitsu for JavaScript evaluation, DOM manipulation, page navigation. Supports multiple BlazorWebViews per app with independent targeting\n- **Unified Logging** — Native `ILogger` and WebView `console.log/warn/error` unified into a single log stream with source filtering\n- **Network Request Monitoring** — Automatic HTTP traffic interception via DelegatingHandler with real-time WebSocket streaming, body capture, and JSONL output\n- **Broker Daemon** — Automatic port assignment and agent discovery for simultaneous multi-app debugging\n- **CLI Tool** (`maui-devflow`) — Scriptable commands for both native and Blazor automation\n- **Driver Library** — Platform-aware (Mac Catalyst, Android, iOS Simulator, Linux/GTK) orchestration\n- **AI Skill** — Claude Code skill (`.claude/skills/maui-ai-debugging`) for AI-driven development workflows\n\n## Quick Start\n\n### AI-Assisted Setup (Recommended)\n\nThe fastest way to get started is to let your AI agent set everything up using the included skill:\n\n**1. Install the CLI tool and download the skill:**\n\n```bash\ndotnet tool install --global Redth.MauiDevFlow.CLI\nmaui-devflow update-skill\n```\n\n**2. Ask your AI agent to set up MauiDevFlow:**\n\n\u003e Use the maui-ai-debugging skill to integrate MauiDevFlow into my MAUI app.\n\u003e Add the NuGet packages, configure MauiProgram.cs, and set up everything\n\u003e needed for debugging. Then build, run, and verify it works.\n\nThe skill includes a complete setup guide with a step-by-step checklist, platform-specific\nconfiguration (entitlements, port forwarding), and the full command reference. The agent\nwill handle NuGet packages, code changes, Blazor script tags, and verification.\n\n### Manual Setup\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to expand manual setup steps\u003c/summary\u003e\n\n#### 1. Add NuGet Packages\n\n```xml\n\u003cPackageReference Include=\"Redth.MauiDevFlow.Agent\" Version=\"*\" /\u003e\n\u003cPackageReference Include=\"Redth.MauiDevFlow.Blazor\" Version=\"*\" /\u003e  \u003c!-- Blazor Hybrid only --\u003e\n\u003c!-- For Linux/GTK apps, use Agent.Gtk and Blazor.Gtk instead --\u003e\n```\n\n#### 2. Configure MauiProgram.cs\n\n```csharp\n// MauiProgram.cs\nusing MauiDevFlow.Agent;\nusing MauiDevFlow.Blazor;\n\nvar builder = MauiApp.CreateBuilder();\n// ... your existing setup ...\n\n#if DEBUG\nbuilder.Services.AddBlazorWebViewDeveloperTools();\nbuilder.AddMauiDevFlowAgent();\nbuilder.AddMauiBlazorDevFlowTools(); // Blazor Hybrid only\n#endif\n```\n\n**Agent options:** `Port` (default 9223), `Enabled` (default true), `MaxTreeDepth` (0 = unlimited). Port is also configurable via `.mauidevflow` or `-p:MauiDevFlowPort=XXXX`.\n\n**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.\n\nBoth methods extend `MauiAppBuilder`.\n\n#### 3. Port Configuration (optional)\n\nThe CLI includes a **broker daemon** that automatically assigns ports to each running agent —\nno manual configuration needed for most workflows. Run `maui-devflow list` to see all connected\nagents and their ports.\n\nFor explicit port control (or when the broker isn't available), create a `.mauidevflow` in\nyour project directory:\n\n```json\n{ \"port\": 9347 }\n```\n\nBoth the build and CLI auto-detect this file — no flags needed. See [broker documentation](docs/broker.md) for details.\n\n#### 3. Blazor Hybrid: Automatic Setup\n\nThe `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`.\n\n\u003e **Note:** If auto-injection doesn't work in your setup, you can add the script tag manually in `wwwroot/index.html`:\n\u003e ```html\n\u003e \u003cscript src=\"chobitsu.js\"\u003e\u003c/script\u003e  \u003c!-- Add before \u003c/body\u003e --\u003e\n\u003e ```\n\n#### 4. Install CLI Tools\n\n```bash\ndotnet tool install --global Redth.MauiDevFlow.CLI\ndotnet tool install --global androidsdk.tool    # android (SDK, AVD, device management)\ndotnet tool install --global appledev.tools     # apple (simulators, provisioning, certificates)\n```\n\n#### 5. Platform-Specific Setup\n\n- **Mac Catalyst:** Add `com.apple.security.network.server` entitlement (see [setup guide](.claude/skills/maui-ai-debugging/references/setup.md#5-mac-catalyst-entitlements))\n- **Android Emulator:** Run `adb reverse tcp:19223 tcp:19223` (broker) and `adb forward tcp:\u003cport\u003e tcp:\u003cport\u003e` (agent — get port from `maui-devflow list`)\n- **iOS Simulator:** No extra setup needed\n- **Linux/GTK:** No extra setup needed (see [Linux guide](.claude/skills/maui-ai-debugging/references/linux.md))\n\n\u003c/details\u003e\n\n### Verify It Works\n\n```bash\n# Wait for an agent to connect (blocks until ready)\nmaui-devflow wait\n\n# List all connected agents (via broker)\nmaui-devflow list\n\n# Check agent connection\nmaui-devflow MAUI status\n\n# Dump visual tree (all windows)\nmaui-devflow MAUI tree\n\n# Dump visual tree for a specific window (0-based index)\nmaui-devflow MAUI tree --window 1\n\n# Take screenshot\nmaui-devflow MAUI screenshot --output screen.png\n\n# Take screenshot of a specific element\nmaui-devflow MAUI screenshot --id HeaderLabel --output header.png\nmaui-devflow MAUI screenshot --selector \"Button\" --output button.png\n\n# Fetch application logs\nmaui-devflow MAUI logs --limit 50\n\n# Filter by source (native ILogger or Blazor WebView console)\nmaui-devflow MAUI logs --source webview\nmaui-devflow MAUI logs --source native\n\n# Screen recording (start/stop)\nmaui-devflow MAUI recording start --timeout 30\n# ... interact with the app ...\nmaui-devflow MAUI recording stop\n\n# Network request monitoring\nmaui-devflow MAUI network              # live monitor (Ctrl+C to stop)\nmaui-devflow MAUI network --json       # JSONL streaming for AI\nmaui-devflow MAUI network list         # one-shot dump of recent requests\nmaui-devflow MAUI network detail \u003cid\u003e  # full headers + body for a request\nmaui-devflow MAUI network clear        # clear captured requests\n\n# Live edit native properties (no rebuild)\nmaui-devflow MAUI set-property HeaderLabel TextColor \"Tomato\"\nmaui-devflow MAUI set-property HeaderLabel FontSize \"32\"\n\n# Blazor WebView (if applicable)\nmaui-devflow cdp status\nmaui-devflow cdp snapshot\n```\n\n## Blazor WebView CDP Commands\n\nFor Blazor Hybrid apps with the CDP bridge configured:\n\n```bash\n# Check CDP connection and WebView count\nmaui-devflow cdp status\n\n# List all registered WebViews (useful when app has multiple BlazorWebViews)\nmaui-devflow cdp webviews\nmaui-devflow cdp webviews --json\n\n# Page snapshot (useful for AI agents — accessible text representation of DOM)\nmaui-devflow cdp snapshot\n\n# Evaluate JavaScript\nmaui-devflow cdp Runtime evaluate \"document.title\"\n\n# DOM queries\nmaui-devflow cdp DOM querySelector \"button.btn-primary\"\nmaui-devflow cdp DOM querySelectorAll \"a.nav-link\"\nmaui-devflow cdp DOM getOuterHTML \"div.container\"\n\n# Input actions\nmaui-devflow cdp Input dispatchClickEvent \"button\"\nmaui-devflow cdp Input fill \"input#name\" \"John\"\nmaui-devflow cdp Input insertText \"typed text\"\n\n# Page navigation\nmaui-devflow cdp Page navigate \"https://example.com\"\nmaui-devflow cdp Page reload\nmaui-devflow cdp Page captureScreenshot\n\n# Get full page HTML source\nmaui-devflow cdp source\nmaui-devflow cdp source --webview BlazorLeft\n\n# Live CSS/DOM editing (experiment without rebuilding)\nmaui-devflow cdp Runtime evaluate \"document.querySelector('h1').style.color = 'tomato'\"\nmaui-devflow cdp Runtime evaluate \"document.querySelectorAll('.item').forEach(el =\u003e el.style.borderRadius = '20px')\"\nmaui-devflow cdp Runtime evaluate \"document.documentElement.style.setProperty('--bg-color', '#1a1a2e')\"\nmaui-devflow cdp Runtime evaluate \"document.head.insertAdjacentHTML('beforeend', '\u003cstyle\u003e.btn { background: hotpink !important; }\u003c/style\u003e')\"\n```\n\n### Multi-WebView Targeting\n\nApps with multiple `BlazorWebView` controls (e.g. side-by-side views, split layouts) are\nfully supported. Each WebView registers independently with the agent using its `AutomationId`.\n\n```bash\n# List all WebViews — shows index, AutomationId, and ready status\nmaui-devflow cdp webviews\n\n# Target a specific WebView by AutomationId\nmaui-devflow cdp --webview BlazorLeft snapshot\nmaui-devflow cdp -w BlazorRight Runtime evaluate \"document.title\"\n\n# Target by index (0-based)\nmaui-devflow cdp -w 0 Runtime evaluate \"1+1\"\nmaui-devflow cdp -w 1 DOM querySelector \"h1\"\n```\n\nWithout `--webview`, all CDP commands target the first registered WebView (index 0).\nThe `--webview` (`-w`) option is available on every `cdp` subcommand.\n\n\u003e **Tip:** Live CSS/DOM edits are immediate and non-destructive — changes are lost on page reload,\n\u003e making them safe for experimentation before committing to code.\n\n\u003e **Note:** On iOS/Mac Catalyst, `Page.reload`, `Page.navigate`, and `Input.insertText` are\n\u003e intercepted and handled via native WKWebView APIs. This is necessary because these operations\n\u003e destroy/recreate the JavaScript context — the Chobitsu debug bridge is automatically\n\u003e re-injected after reload/navigation completes.\n\n## Agent API\n\nThe Agent runs inside the MAUI app and exposes an HTTP/JSON REST API. The port is\nauto-assigned by the broker (range 10223–10899), or configurable via `.mauidevflow` / `--agent-port`.\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/status` | GET | Agent version, platform, app info, window count |\n| `/api/tree?depth=N\u0026window=W` | GET | Visual tree as JSON (window: 0-based index) |\n| `/api/element/{id}` | GET | Single element by ID |\n| `/api/query?type=\u0026text=\u0026automationId=` | GET | Find matching elements |\n| `/api/action/tap` | POST | Tap element `{\"elementId\":\"...\"}` |\n| `/api/action/fill` | POST | Fill text `{\"elementId\":\"...\",\"text\":\"...\"}` |\n| `/api/action/clear` | POST | Clear text `{\"elementId\":\"...\"}` |\n| `/api/action/focus` | POST | Focus element `{\"elementId\":\"...\"}` |\n| `/api/action/scroll` | POST | Scroll by delta or scroll element into view `{\"elementId\":\"...\",\"deltaX\":0,\"deltaY\":200}` |\n| `/api/action/resize?window=W` | POST | Resize window `{\"width\":800,\"height\":600}` |\n| `/api/screenshot?window=W\u0026id=ID\u0026selector=SEL` | GET | PNG screenshot. Full window, or element by ID/selector |\n| `/api/hittest?x=X\u0026y=Y\u0026window=W` | GET | Find elements at a point (deepest first). Returns element IDs, types, bounds |\n| `/api/property/{id}/{name}` | GET | Get property value |\n| `/api/property/{id}/{name}` | POST | Set property `{\"value\":\"...\"}` |\n| `/api/logs?limit=N\u0026skip=N\u0026source=S` | GET | Application logs (source: `native`, `webview`, or omit for all) |\n| `/api/network?limit=N\u0026host=H\u0026method=M` | GET | Recent captured HTTP requests (summary) |\n| `/api/network/{id}` | GET | Full request/response details (headers, body) |\n| `/api/network/clear` | POST | Clear captured request buffer |\n| `/ws/network` | WS | WebSocket stream of HTTP requests (replay + live) |\n| `/api/cdp` | POST | Forward CDP command to Blazor WebView. Use `?webview=\u003cid\u003e` to target a specific WebView |\n| `/api/cdp/webviews` | GET | List registered CDP WebViews (index, AutomationId, elementId, ready status) |\n| `/api/cdp/source` | GET | Get page HTML source. Use `?webview=\u003cid\u003e` to target a specific WebView |\n\n## Project Structure\n\n```\nMauiDevFlow.sln\n.claude/skills/\n└── maui-ai-debugging/          # AI skill for Claude Code\nsrc/\n├── MauiDevFlow.Agent/          # In-app agent (NuGet library for MAUI apps)\n├── MauiDevFlow.Agent.Core/     # Platform-agnostic agent core (shared by Agent \u0026 Agent.Gtk)\n├── MauiDevFlow.Agent.Gtk/      # GTK/Linux agent (NuGet library for Maui.Gtk apps)\n├── MauiDevFlow.Blazor/         # Blazor WebView CDP bridge (Chobitsu)\n├── MauiDevFlow.Blazor.Gtk/     # Blazor CDP bridge for WebKitGTK on Linux\n├── MauiDevFlow.CLI/            # CLI tool (maui-devflow)\n├── MauiDevFlow.Driver/         # Driver library (connects to Agent, platform tools)\n└── SampleMauiApp/              # Sample todo app (native + Blazor Hybrid via Shell)\ntests/\n├── MauiDevFlow.Console/        # Console test app for CDP\n└── MauiDevFlow.Tests/          # Unit and integration tests\ndocs/\n├── broker.md                   # Broker daemon architecture and API\n└── setup-guides/               # Platform-specific setup (Android, Apple, Windows)\n```\n\n### Sample App\n\nThe `SampleMauiApp` is a shared-state todo list with both a native MAUI page and a Blazor\nHybrid page, connected via Shell navigation (`//native` and `//blazor` routes). It demonstrates:\n\n- **Shared `TodoService`** — both pages read/write the same data, changes reflect immediately\n- **Shell navigation** — switch between tabs via `maui-devflow MAUI navigate \"//native\"` etc.\n- **Dark mode support** — both native (AppThemeBinding) and Blazor (`@media prefers-color-scheme`) adapt to system theme\n- **Description field** — todo items support title + optional description on both pages\n- **Multi-WebView** — the `//multiblazor` route shows two side-by-side BlazorWebViews (`BlazorLeft` and `BlazorRight`) for testing multi-WebView CDP targeting\n\n## Platform Support\n\n| Platform | Agent | CDP/Blazor | Network Setup |\n|----------|-------|------------|---------------|\n| Mac Catalyst | ✅ | ✅ | Direct localhost |\n| iOS Simulator | ✅ | ✅ | Shares host network |\n| Android Emulator | ✅ | 🔄 | `adb reverse` (broker) + `adb forward` (agent) |\n| Windows | 🔄 | 🔄 | Direct localhost |\n| Linux/GTK | ✅ | ✅ | Direct localhost |\n\n### Companion Tools\n\n| Tool | Install | Purpose |\n|------|---------|---------|\n| `maui-devflow` | `dotnet tool install -g Redth.MauiDevFlow.CLI` | App automation \u0026 Blazor CDP |\n| `android` | `dotnet tool install -g androidsdk.tool` | Android SDK, AVD, device management |\n| `apple` | `dotnet tool install -g appledev.tools` | iOS simulators, provisioning, certificates |\n| `adb` | Android SDK platform-tools | Device communication, port forwarding, logs |\n| `xcrun simctl` | Xcode command-line tools | iOS simulator lifecycle |\n\n## AI Agent Integration\n\nThis project includes a Claude Code skill (`.claude/skills/maui-ai-debugging`) that teaches AI\nagents the complete build → deploy → inspect → fix feedback loop. The skill covers:\n\n- Installing and configuring all required tools\n- Building and deploying to iOS simulators, Android emulators, Mac Catalyst, and Linux/GTK\n- Using `maui-devflow` to inspect visual trees, interact with elements, and take screenshots\n- Using CDP to inspect and manipulate Blazor WebView content\n- Automatic port discovery via the broker daemon for multi-app workflows\n- Managing simulators/emulators with `apple`, `android`, `xcrun simctl`, and `adb`\n\n### Installing the Skill\n\nThe CLI can download the latest skill files directly from GitHub into your project:\n\n```bash\n# Interactive — shows files and asks for confirmation\nmaui-devflow update-skill\n\n# Skip confirmation\nmaui-devflow update-skill -y\n\n# Download to a specific directory\nmaui-devflow update-skill -o /path/to/my-project\n\n# Use a different branch\nmaui-devflow update-skill -b dev\n```\n\nThis downloads the skill files into `.claude/skills/maui-ai-debugging/` relative to the output\ndirectory (or current directory if `--output` is not specified). Existing files are overwritten.\nThe file list is discovered dynamically from the repository, so new reference docs are picked up\nautomatically.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredth%2Fmauidevflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredth%2Fmauidevflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredth%2Fmauidevflow/lists"}