Accessibility tree, native macOS apps: the two practical ways to read one in 2026

Two practical paths. (1) Accessibility Inspector. Open Xcode, then Xcode > Open Developer Tool > Accessibility Inspector. Point the inspector at any running app's window. The left pane shows the tree, the right pane shows attributes (AXRole, AXTitle, AXValue, AXPosition, AXSize, available actions). (2) The macos-use MCP server. Install it once, then any tool call (open_application_and_traverse, refresh_traversal) writes the entire tree to /tmp/macos-use/<timestamp>_<tool>.txt in a flat one-element-per-line format. You read it with cat, grep, or any text tool. Path 1 is for human inspection; path 2 is for any code or AI agent that needs to consume the tree.

An element line is `[Role] "text" x:N y:N w:W h:H visible`. For example: `[AXButton (button)] "Send" x:820 y:612 w:60 h:28 visible`. Role first, then the element's text in quotes (truncated to 80 chars at Sources/MCPServer/main.swift:997), then top-left coordinates and width/height as integers, then the literal token `visible` if the element falls inside the current window bounds. The format is produced by formatElementLine at main.swift:993-1010 and the file is written by buildFlatTextResponse at main.swift:1013-1058.

Because the AX root for an application is always AXUIElementCreateApplication(pid). Every tree the OS exposes is rooted at a process. main.swift uses that call at three sites (lines 244, 309, 349) to get the application root before walking. One running Mac with ten apps has ten parallel AX trees. A single app's tree contains all of its windows in one tree, including hidden ones (Preferences, Sparkle update dialogs, secondary windows). The macos-use server checks 'visible' against the union of all the app's window bounds (main.swift:621-629), which is why the `visible` token in the dump can mark elements outside what looks like the foreground window.

Because the tree's quality depends on which UI toolkit the app was built with, even if the app menu icon and the .app bundle look the same. AppKit apps (Mail, Finder, Notes-the-old-one) emit a clean tree with AXButton, AXTextField, AXMenuItem and proper press actions. SwiftUI apps emit a similar tree, often more verbose because every modifier becomes a wrapper element. Mac Catalyst apps (UIKit-on-Mac, e.g. Messages, Maps) emit a tree that looks correct but where many nodes silently ignore synthetic CGEvent clicks; you have to call kAXPressAction or kAXValueAttribute on the element directly. Electron apps (Slack, Discord, VS Code) emit thousands of AXGroup and AXStaticText nodes from a Chromium accessibility shim, which an agent can read but which is far less actionable than an AppKit tree.

Yes, that's the whole point of the Accessibility API. The host you're reading from (Xcode, Terminal, Claude Code, Cursor, the macos-use MCP host) needs to be granted Accessibility permission in System Settings > Privacy & Security > Accessibility. Granting that, AXUIElementCreateApplication(pid) succeeds for any app the OS can see, with no cooperation from the target. On Sequoia and later, capturing a screenshot of the same window also requires Screen Recording permission for the host. macos-use needs both because every tool call writes a /tmp/macos-use/<ts>_<tool>.txt and a /tmp/macos-use/<ts>_<tool>.png next to each other.

Inspector is a GUI for a human. You hover over a window, you see the element under your cursor, you read its attributes in the right pane, you click around the tree. It's the right tool when you're auditing an app you're building or trying to understand why a control isn't reachable. The macos-use dump is a text file. You can pipe it through grep to find every AXButton, you can diff two dumps to see what changed after an action, you can hand the file to an LLM as context. It's the right tool when you want to drive an app from a script or an AI agent. They are not in competition; they answer different questions.

Mostly. Identifiers (AXIdentifier when set), roles, and the rough shape of the tree stay stable. Coordinates change with window position and size. AXValue changes with state. Some toolkits insert ephemeral tooltip and focus-ring elements that come and go between traversals. macos-use handles this by treating coordinate-only changes as noise (filtered at main.swift:681-682) and by dropping a defined set of structural-only and scroll-bar nodes (isScrollBarNoise at main.swift:591-597, isStructuralNoise at main.swift:599-607) so a diff between two traversals only highlights changes that an agent can act on.

Sometimes, partly. Safari and any app embedding WKWebView surface DOM accessibility through the AX bridge as AXWebArea with nested AXLink, AXButton, AXStaticText, etc. The tree you get is roughly what VoiceOver would announce, not the full DOM. Heading levels, link text, form labels are all present; CSS-styling-only changes are not. Electron apps (Chromium-based) follow the same model. A native AppKit app that does not use a web view has a much richer per-control tree than the same screen rendered in a web view inside the same app.

Install the server with `claude mcp add macos-use -- npx -y mcp-server-macos-use`. Restart the Claude Code session so the new MCP is registered. Grant Accessibility permission to your terminal app on the first call. Then ask Claude: 'open Mail and dump the AX tree'. The agent will call macos-use_open_application_and_traverse({identifier: 'Mail'}). The response includes a `file:` field with the .txt path under /tmp/macos-use/ and a `screenshot:` field with the .png. You can `cat`, `grep`, or open the .txt yourself; you can `open` the .png to see the captured window.

Many full-screen game engines (Metal-only renderers without AppKit views) expose only a top-level AXWindow with no children worth speaking of. DRM-protected video players the same. CGWindowListCreateImage on Sequoia returns blank or menu-bar-only frames if Screen Recording isn't granted. None of this is something a tree-walker can fix; the app simply hasn't published anything to walk. macos-use will return a small tree and a screenshot. The agent's plan needs to fall back to coordinate-driven clicking against the screenshot for those cases, or to a different control surface entirely.

Order-of-magnitude: tens to hundreds of milliseconds for AppKit, hundreds of milliseconds to a couple of seconds for SwiftUI-heavy or Electron apps with large element counts. The traversal time is included in the file header line of the dump (`# <app> — N elements (Xs)`, written at main.swift:1018). The dominant cost is AXUIElementCopyAttributeValues per node times depth-first traversal; that's why the server caches the full tree on disk and returns only the diff after disruptive actions like click/type/press, not the whole tree again.