winui-devtools

If you can't run winapp yourself (no shell, or the command is denied), give the user the exact winapp devtools / winapp run command(s) that would answer their question instead of only reasoning from source. Say which values you read from source and which only the running app can confirm.

Start with the target

Use winapp ui and the winapp-ui-automation skill for general Windows UI Automation: actions, screenshots, waits and accessibility across app frameworks. DevTools is for WinUI 3 XAML trees/source, bindings and dependency-property diagnosis or edits. Both tools accept an element's AutomationId as its selector, so an AutomationId from winapp ui works in winapp devtools and the aid= shown by DevTools works in winapp ui invoke/click. Generated selectors (slugs, handles) belong to one tool; copy a fresh one from that tool's inspect or search.

winapp run .

For a WinUI project this starts DevTools with its in-app toolbar and waits for the app (it is off in CI, with --no-launch, --without-alias or --on sandbox, and for folders, .cs files and non-WinUI projects; pass --devtools on for a WinUI target that isn't detected automatically). Known WPF-only and Windows Forms-only projects are rejected before launch; use --devtools off to run them and winapp ui to inspect their accessible controls. Let the user leave comments there: turn on Comments in the toolbar, click an element, type, press Enter (Shift+Enter for a new line), or click the next element to save and move on. Select element opens the DevTools window on the element the user clicks, then turns picking off so the next click reaches the app. Ctrl+Shift+F12 moves keyboard focus to the toolbar (showing it if the user hid it), and Esc returns it. Use a second terminal for commands, or add --detach to return to the terminal with the app still running and its PID printed. Use an exact PID with -a when multiple apps are attached. Never stop another app automatically to make a rebuild succeed.

--json is optional output formatting for structured consumers, not the default agent workflow. It does not hide the overlay. Use --devtools headless for an authorized headless inspection launch: nothing is drawn in the app, and Ctrl+Shift+F12 brings up the toolbar. --devtools off runs without DevTools; don't change the user's default (winapp config set run.devtools) unless they ask. For a script, capture $run = winapp run . --devtools on --detach --json | ConvertFrom-Json, then use winapp devtools inspect -a $run.ProcessId. After the human leaves a comment, follow the comment workflow below. If attachment succeeds but the overlay reports a missing XAML resource/type, see visual UI prerequisites; do not mistake unavailable visual UI for failed protocol attachment.

Packaged aliases are prepared automatically in the staged manifest, not manually authored in the source manifest. When DevTools starts by default and how to choose, including dotnet run's -p:WinAppRunDevTools, is in Turn DevTools on or off.

Do not adopt a different running instance when launch fails. Attaching to an existing app is explicit and headless by default:

winapp devtools list --include-available
winapp devtools attach --pid <pid> --source-root <project folder>

--source-root gives the app its project folder, so in-app comments go to the same store as with winapp run; an app started without winapp run has none. list and attach only take WinUI 3 apps.

Late attach cannot provide startup-only binding hooks or missing XAML source information. Obtain permission before launching, injecting into, or mutating an app; do not use an unrelated running app as a test fixture. Live commands require an attached target. Only after injection is authorized, use --attach with an explicit target to attach as part of a live command. Choosing a PID or HWND alone never authorizes injection.

Inspect inside Sandbox

$run = winapp run . --on sandbox --devtools on --detach --json | ConvertFrom-Json
winapp devtools inspect --on sandbox --app $run.appSelector
winapp devtools comments list --status open --json

Use --on sandbox --app <pid> from fresh guest discovery for live commands; the emitted appSelector remains suitable for scripts tied to one launch. Names and window titles work when unambiguous. Never fall back to a local app. The overlay runs in the guest; comments persist in the host project store. Source snapshots are read-only and project-scoped. After app exit, use ordinary host comments commands with --source-root. Follow the Sandbox DevTools workflow for supported inputs, options, late attachment and disconnected-save handling. Sandbox selection is not consent to enable Windows features, install, reboot, repair a shared guest or start a live test.

Turn the user's comments into changes

Start with comments the human leaves through the running app's overlay:

winapp devtools comments list
winapp devtools comments list --status open --json --source-root <project-dir>
winapp devtools comments get <comment-id>

Verify the source locations, make the requested change, and check the result before resolving the comment:

winapp devtools comments update <comment-id> --status resolved --note "Implemented and checked"

If get-source labels a declaration likely source, show the declaration and its missing-evidence explanation to the user before capturing a source-anchored comment. Pass --confirm-likely-source only after that explicit confirmation; do not add it automatically to recover from a refused save. See source attribution for disk-matched and likely-source limits, including rebuild/hot-reload uncertainty.

Saved list/get/update/delete use the host store without connecting to Sandbox. Choose it with --source-root, or with -a <pid> on list/get/update/delete to use the running app's project; none of them take --on. --source-root takes precedence. If the connection fails, follow the comment store recovery instructions; do not retry against the current folder's store. Mutations refresh the markers of running DevTools apps (local and Sandbox) that use the same store; no --app is needed. See the guide for save-warning behavior. Offline --file/--name comments can acquire markers at launch or refresh only when the saved declaration still matches one verified live instance. A refusal leaves the comment saved and explains why; never resolve it by name alone. See offline markers.

Use current hits, not historical anchor.line. Runtime text need not appear in XAML. When requiresConfirmation is true, show the ranked candidates and obtain the user's confirmation before editing; never promote a weak hit by proximity. See comment identity.

A comment that is not linked to source (no anchor.sourceFile, often an app with no project) has no candidates to confirm. Search the whole project, including code that builds or loads XAML at runtime, for its x:Name, AutomationId, or text (anchor.identity.name, automationId, content); context.windowTitle names the window it was in. Show the match to the user before editing when more than one place fits.

For visual requests ("warmer", "less contrast"), read context first: context.style is the element's style resource and context.brushes lists each brush's resolved value with its resourceKey, resourceKind and, for project styles, the file and line of the setter. Change that resource or setter instead of searching for the color. Without a resourceKey, the value comes from the platform's default style; override it locally or with the control's lightweight styling resource.

Flag unconfirmed anchors instead of guessing. Keep durable comment success distinct from a marker-refresh warning. Source candidates and line numbers are hints to verify, not proof of identity. Use comments add only when programmatic comment authoring is explicitly useful; do not create feedback instead of reading the user's existing comments.

Inspect, then act

Prefer inspect, search, get-property, get-layout, get-source, and diagnose-binding. inspect and search show the confirmed declaration as File.xaml:line (JSON file, line, endLine); an element with only a file name has no confirmed line. Target an exact PID when multiple apps are running. Reuse a selector or handle from fresh inspection; never guess an ambiguous element. For multiple windows, get --window <HWND> from winapp devtools call Surface.list -a <pid>. Get --root <element-handle> from window-scoped inspect; do not assume Surface.list's rootHandle contains the app's content. The subtree must belong to --window when both are supplied. Never reuse a closed window or stale root, and do not substitute UIA slugs. Use search --of-type TextBlock --with 'FontSize>=20' --fields 'Text,FontSize' for multi-element reads; repeat --with for AND. A definite typed mismatch excludes an element even if another predicate value is unknown; a local null value does not match == or *= with a non-empty value. Without a mismatch, unknown values still block exact targeting. Check completeness and unevaluated candidates before acting. Query-targeted get-property and set-property --value require exactly one provable match; omit the positional selector. Follow the query targeting and timeout rules; use bounded failure diagnostics to identify unresolved candidates, not to bypass the uniqueness guard. Never retry an indeterminate write automatically. For disk-matched source declarations and their limits, follow the source-coordinate guidance before editing XAML or capturing a source-anchored comment.

Use set-property <selector> <property> <value> for an authorized in-memory change. Report its observed read-back, not the requested value as if it succeeded. If the result has replacedBinding, say so: the local value replaced a {Binding} or overrode an x:Bind, and restarting the app restores it. This does not edit source. call is for advertised protocol methods without a curated command; it rejects internal methods and requires --attach to inject.

For resource-backed brush edits, pass a fixed color to set-property, not {ThemeResource key} or {StaticResource key}. To change the reference, edit XAML and rebuild, or use the inspector's resource editor for a live edit; see the resource editing instructions.

Before a binding edit or restore, follow the guide's binding safety and confirmation workflow. Do not treat a forward evaluation as proof of synchronization or an owner refresh as proof that the selected property was restored.

See the DevTools guide and Advanced DevTools for launch restrictions, binding capture/restore, store location, commands and troubleshooting. Use winapp devtools <command> --help for exact options.