@superbased/macos-ax

macOS Accessibility tree inspector via AXUIElement / NSAccessibility. Published as an optional dependency of superbased for AI-agent UI automation; not intended as a standalone consumer surface.

Requirements

• macOS 10.15+ (arm64 or x64)
• Node.js 20+
• The host process must be granted Accessibility permission via System Settings → Privacy & Security → Accessibility. Use promptForTrust() to show the system dialog.

Install

npm install @superbased/macos-ax

API

import {
  isTrusted,
  promptForTrust,
  getTreeForPid,
  getFocusedElement,
} from '@superbased/macos-ax';

// Whether the host process has Accessibility permission.
isTrusted();             // boolean

// If not trusted, shows the system dialog redirecting to Settings.
promptForTrust();        // boolean (trust state after the prompt)

// Walk the AX tree for a running app.
const tree = getTreeForPid(1234, { maxDepth: 16, includeAttributes: false });

// What element is currently focused?
getFocusedElement();     // AxNode | null

Error shape

try {
  getTreeForPid(1234);
} catch (err) {
  // err.code is one of:
  //   'accessibility_not_trusted' — call promptForTrust() first
  //   'no_application_for_pid'    — no running app matches the pid
}

Building from source

npm install
npm run build

binding.gyp links ApplicationServices, Foundation, AppKit, CoreFoundation.

License

MIT. Authored by Gaja AI Private Limited.