accessibility-sys AXUIElementCreateSystemWide, decoded

What the crate page actually tells you (and what it leaves out)

accessibility-sys is a binding crate, nothing more. Its job is to hand Rust the raw symbols from Apple's HIServices headers so you can call the C Accessibility API. The published facts are short and worth pinning down before you write a line:

• Version 0.2.0, authored by eiz, dual licensed MIT or Apache-2.0.
• One dependency: core-foundation-sys ^0.8. It targets Apple Darwin.
• docs.rs reports 0% of the crate is documented, which is why every symbol renders as a bare signature.

That last point is the trap. The signatures are correct, but a signature does not tell you that the system-wide element behaves completely differently from an application element, or that it returns a usable ref even when your process has no Accessibility permission and every later call fails. The behavior lives in Apple's C semantics, not in the Rust doc string. Below is the part the rendered docs cannot give you.

The four symbols you almost always need together

Reaching for AXUIElementCreateSystemWide alone is rare. In practice you call it next to three siblings: the per-app constructor, the attribute reader, and the trust check. Here are the real signatures as exported by accessibility-sys.

// The system-wide root: no arguments.
pub unsafe extern "C" fn AXUIElementCreateSystemWide() -> AXUIElementRef;

// A single application's root: takes its process id.
pub unsafe extern "C" fn AXUIElementCreateApplication(pid: pid_t) -> AXUIElementRef;

// Read one attribute (e.g. kAXFocusedUIElementAttribute) off any element.
pub unsafe extern "C" fn AXUIElementCopyAttributeValue(
    element: AXUIElementRef,
    attribute: CFStringRef,
    value: *mut CFTypeRef,
) -> AXError;

// Is this process trusted for Accessibility? Pass kAXTrustedCheckOptionPrompt
// in the options dictionary to surface the System Settings prompt.
pub unsafe extern "C" fn AXIsProcessTrustedWithOptions(
    options: CFDictionaryRef,
) -> bool;

The system-wide constructor takes nothing; the application constructor takes a pid_t. That single difference is the whole mental model.

What the system-wide root is genuinely good for

Keep the system-wide element for cross-application questions. The moment you want to read a specific window or click a specific button, switch to a per-pid element.

The order the calls actually happen in

A working session is never just one function. This is the sequence that produces a real element instead of a permission error.

A minimal read of the focused element

Here is the smallest honest example with the raw accessibility-sys surface: gate on trust, create the system-wide root, copy the focused element. The unsafe is unavoidable because these are C bindings.

use accessibility_sys::{
    kAXFocusedUIElementAttribute, AXIsProcessTrustedWithOptions,
    AXUIElementCopyAttributeValue, AXUIElementCreateSystemWide,
};
use core_foundation::base::TCFType;
use core_foundation::string::CFString;
use std::ptr;

unsafe {
    // 1. No trust, no elements. Pass an empty options dict here for brevity;
    //    pass kAXTrustedCheckOptionPrompt = true to show the system prompt.
    if !AXIsProcessTrustedWithOptions(ptr::null()) {
        eprintln!("not trusted for Accessibility yet");
        return;
    }

    // 2. The zero-argument root.
    let system_wide = AXUIElementCreateSystemWide();

    // 3. Ask it for whatever currently has focus, anywhere on screen.
    let attr = CFString::new(kAXFocusedUIElementAttribute);
    let mut focused: core_foundation::base::CFTypeRef = ptr::null();
    let err = AXUIElementCopyAttributeValue(
        system_wide,
        attr.as_concrete_TypeRef(),
        &mut focused,
    );

    println!("AXError = {err}, got focused = {}", !focused.is_null());
    // CFRelease(system_wide) and CFRelease(focused) when done.
}

Most code should not look like that. The safe accessibility crate (also by eiz) wraps the same call so you skip the raw pointers and the manual release:

use accessibility::{AXUIElement, AXAttribute};

let system_wide = AXUIElement::system_wide();
let focused = system_wide
    .attribute(&AXAttribute::focused_uielement());
// Drop releases the underlying AXUIElementRef for you.

// And for a specific app, by pid:
let app = AXUIElement::application(pid);
let windows = app.attribute(&AXAttribute::windows());

From four FFI calls to an automation framework

Reading the focused element is the easy 5%. The hard 95% is everything a real automation tool has to wrap around these bindings: gating and re-checking trust, decoding every AX value type, retrying flaky attribute reads, mapping AX roles to something stable, and giving you a way to find an element by name or role instead of walking children by hand. On Windows the same shape repeats with UI Automation instead of the AX API. The primitives differ; the work is identical.

That wrapper is what Terminator is. It is a desktop automation framework built on native accessibility APIs, shaped like Playwright but pointed at the whole operating system rather than the browser. You write a selector, Terminator resolves it against the accessibility tree, and acts on the element. You do not call AXUIElementCopyAttributeValue in a loop, you do not hand-manage CFRelease, and you do not re-implement the trust dance on every project.

If you are reaching for accessibility-sys because you are building agent or computer-use tooling that has to drive real apps, that is the exact problem Terminator exists to take off your plate, including the MCP server that lets an AI assistant call these capabilities as a tool.