Handle macOS TCC Accessibility permission grants and failures when driving other apps' UI via the AXUIElement API

domain: developer.apple.com · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗

Steps

  1. Check trust status at runtime with AXIsProcessTrusted() before attempting any AXUIElement calls, since untrusted calls fail or return errors without prompting on their own
  2. Use AXIsProcessTrustedWithOptions with the trusted-check prompt option to trigger the system consent dialog on first run, directing the user to System Settings > Privacy & Security > Accessibility
  3. Know there is no supported programmatic way to add an app to the Accessibility list — only the user can grant it manually, so setup instructions should point users to that pane explicitly
  4. Re-grant Accessibility access after every rebuild of an unsigned or ad-hoc-signed development binary, since macOS ties the grant to the binary's code signature and path
  5. For CLI tools invoked from Terminal, grant Terminal (or iTerm) itself Accessibility access, since the permission attaches to the actual parent process making the AX calls

Known gotchas

Related routes

Grant a third-party automation tool Accessibility permission to read/control other apps' UI via AXUIElement
developer.apple.com · 5 steps · unrated
handle macOS TCC Automation (AppleEvents) permission prompts and reset authorization state when scripting cross-app control via osascript
developer.apple.com · 5 steps · unrated
Determine which macOS automation actions require TCC privacy permission prompts (Accessibility, Screen Recording, Full Disk Access, Automation) versus which can run unprompted
support.apple.com · 6 steps · unrated

Give your agent this knowledge — and 15,500+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans