Skip to main content
On this page

View an iOS App's UI Hierarchy on Windows: 3D View Debugging

Inspect the UI of an app running on your iPhone in a 3D exploded view in the browser, read every view's properties and constraints, and change them live.

Last updated

To inspect an iOS app's view hierarchy on Windows, run kxdevice web and capture the app running on your iPhone under View debugger in the browser. You get a 3D exploded view you can rotate, the tree of views and every view's properties, and you can change properties and constraints and see the result on the phone at once. A Debug build made by kxbuild is read while it keeps running. Any other development-signed app is read through a debugger. It works the same on Linux and macOS.

How do I open the view hierarchy viewer?

1. Start the web UI

The iPhone is connected and trusted, see Device setup. Run the command below, open http://127.0.0.1:8780 in a browser and choose View debugger on the left.

2. Capture an app

Pick the app under App to launch and click Launch & capture. If it is already running, pick it under Running process and click Capture. After the UI changes, click Recapture. The selected view stays selected.

> kxdevice web

In-app or debugger: how do the two capture methods differ?

Choose the method next to the capture buttons. The default, Auto, tries in-app first and falls back to the debugger when the app does not support it.

In-appDebugger
Which appsA Debug build made by kxbuild, in the foregroundAny development-signed app
The app during a captureKeeps running, done in about a secondPaused, resumes after about 10 seconds
While the app is being debuggedWorks (when the app is not stopped at a breakpoint)Does not work. End the debug session first
What you can changeEvery property marked writable in the panel, and constraintsalpha, hidden, frame, background color
ExtrasAccessibility elements, how much of each view is visibleExport as a .viewhierarchy document

How do I use the 3D canvas, the tree and the property panel?

WhereWhat you can do
Tree on the leftSearch by class, address or text. Click a row to select a view. A view controller's root view shows the controller's class
Canvas in the middleDrag to rotate, scroll to zoom, click to select. 3D / 2D switches between layers and flat, Spacing sets the distance between layers, Levels shows only some of them
Switches above the canvasHidden shows hidden views, Wireframe draws outlines only, Accessibility draws accessibility elements that are not views as orange outlines
Window pickerWith several windows, look at one, or choose All windows to stack them
Panel on the rightThe selected view's position, size, visible share, accessibility information, images of its own layer and with subviews, and every property of the view and its layer

How do I change properties and constraints live?

With an in-app capture, edit writable properties right in the panel: switches, numbers, text, colors, enum values and rectangles. The phone shows the change at once and the canvas follows. Constraints lists the constraints that place the view. Change a constant, a priority or whether it is active. The section says so when the constraints leave the layout open.

With a debugger capture, change alpha, hidden, frame or background color under Edit on device and click Apply.

These changes last while the app runs and are gone after a restart. Use them to find the right values, then put those into your code or storyboard.

How do I capture the view hierarchy from the command line?

kxdevice viewdebug capture -B com.example.myapp -o tree.json kxdevice viewdebug capture --pid 1234 kxdevice viewdebug snapshot --pid 1234 --id 0x10320b9d0 -o view.png kxdevice viewdebug set --pid 1234 --id 0x10320b9d0 --alpha 0.5 --bg 3366ff kxdevice viewdebug set --pid 1234 --id 0x10320b9d0 --attr v.text='"Hello"'
CommandWhat it does
viewdebug capturePrints the tree. -B names the app (launched when it is not in front), --pid a running process, -o also saves JSON, --until <class> waits for a view of that class first
viewdebug snapshotSaves one view as a PNG. --layer-only takes its own layer alone
viewdebug setChanges a view: --alpha, --hidden, --frame x,y,width,height, --bg RRGGBB. On a Debug build, --attr name=value changes any writable property. Names are in the web panel and in the capture output
viewdebug exportWrites a .viewhierarchy document

Add --backend agent or --backend debugger to any of them to pick the method. Without it the choice is automatic.

How do I export a .viewhierarchy document?

After a debugger capture in the web UI, click Export, or use the command line. The document is compatible with Xcode and opens there. You can also Import it in the web UI later, without the iPhone connected.

> kxdevice viewdebug export -B com.example.myapp -o MyApp.viewhierarchy

How do I let an AI agent read the view hierarchy?

Add kxdevice as an MCP server, and an AI agent reads the tree with the view_hierarchy tool, including text, positions, accessibility information and how much of each view is visible, to check its own UI changes. For the tools that operate the UI, see UI automation.

> claude mcp add kxdevice -- kxdevice mcp

To watch an AI go from one sentence to an app it tests on the iPhone and gets ready for the App Store, see Fully automated development with AI, with a full demo video.

How do I fix a failed capture?

ProblemFix
It says the app is in the background and does not respondBring the app to the front on the iPhone and capture again
It says another debugger is attached to the appEnd that debug session, or use a Debug build made by kxbuild, which can be captured while it is debugged
The captured window is emptyThe app had not drawn its UI yet. Enter a view class that always appears in Wait for class, then click Launch & capture
It says the Developer Disk Image is not mountedClick Mount on the Maintenance page of the web UI, or run kxdevice ddi auto-mount
With in-app selected, it says no app answersThe app must be a Debug build made by kxbuild and be in the foreground. Run kxbuild doctor to update, then build and install again

To operate the UI automatically once you can see it, read UI automation. For breakpoints, see debug iOS apps on iPhone in VS Code.

Next steps