AXUIElement::system_wide() in the Rust accessibility crate: the three patterns the docs don't ship

The function body is one line

Here is the entire constructor, copied from accessibility/src/ui_element.rs on eiz/accessibility. It calls into the C function AXUIElementCreateSystemWide() (declared in accessibility-sys) and wraps the returned AXUIElementRef using Core Foundation's create-rule (the caller owns one retain).

// From eiz/accessibility, accessibility/src/ui_element.rs
impl AXUIElement {
    pub fn system_wide() -> Self {
        unsafe { Self::wrap_under_create_rule(AXUIElementCreateSystemWide()) }
    }

    pub fn application(pid: pid_t) -> Self {
        unsafe { Self::wrap_under_create_rule(AXUIElementCreateApplication(pid)) }
    }
}

That is it. No initialization, no permission check, no error path. The call cannot fail; you always get an element back. Everything that makes this useful, and everything that makes it tricky, lives in the code you write next.

Pattern 1: the Send + Sync newtype

The accessibility crate does not implement Send or Sync on AXUIElement. The struct holds a Core Foundation pointer, and Rust auto-derives neither trait for raw-pointer-bearing types. The compiler is being correct: the crate maintainer has not certified, in code, that the type is thread-safe.

Apple says it is. The ApplicationServices Accessibility API documentation states that AXUIElement functions can be called from any thread; the framework serializes calls against the application's main run loop internally. So you have a type that is safe at the framework level but unsafe in the type system. The accepted fix is a newtype with two unsafe impls and a SAFETY comment that pins the assumption to the API documentation.

The deleted Terminator macOS adapter declared this at the top of crates/terminator/src/platforms/macos.rs. You can read the file in git at git show 0c11011c~1:crates/terminator/src/platforms/macos.rs.

// terminator/crates/terminator/src/platforms/macos.rs (deleted in 0c11011c)
// lines 76-103
#[derive(Clone)]
pub struct ThreadSafeAXUIElement(Arc<AXUIElement>);

// SAFETY: AXUIElement is safe to send and share between threads as Apple's
// accessibility API is designed to be called from any thread. The underlying
// Core Foundation objects manage their own thread safety.
unsafe impl Send for ThreadSafeAXUIElement {}
unsafe impl Sync for ThreadSafeAXUIElement {}

impl ThreadSafeAXUIElement {
    pub fn new(element: AXUIElement) -> Self {
        Self(Arc::new(element))
    }

    pub fn system_wide() -> Self {
        Self(Arc::new(AXUIElement::system_wide()))
    }

    pub fn application(pid: i32) -> Self {
        Self(Arc::new(AXUIElement::application(pid)))
    }
}

Three things to notice. The wrapper holds an Arc, not the raw element, so cloning is cheap and reference counting is correct. The new constructor takes an existing AXUIElement (you get those out of attribute reads, see Pattern 3). The two static constructors mirror the high-level crate's API: system_wide() for the global root, application(pid) for a specific process. Without this newtype, every Tokio task that touches an AX element fails to compile with a Send bound error.

Pattern 2: the permission gate

The call to system_wide() itself does not require any permission. You always get a valid element handle back. What needs permission is everything you would do with that handle: reading any attribute, listing any child, performing any action.

The failure mode without permission is silent, not loud. Reading AXFocusedApplication on an unauthorized process returns kAXErrorAPIDisabled (-25200) or kAXErrorNotImplemented (-25208) depending on the macOS version, and attribute_names() returns an empty list. Your code looks like it works, then nothing happens, and you spend two hours wondering whether you traversed the tree wrong.

The fix is to call AXIsProcessTrustedWithOptions before any attribute read, with the AXTrustedCheckOptionPrompt option set to true so the system shows the user the prompt the first time. The accessibility crate does not export this function as of writing, so you link it directly through #[link(name = "ApplicationServices", kind = "framework")]. The Terminator adapter did this in MacOSEngine::new, at lines 119 to 148:

// terminator/crates/terminator/src/platforms/macos.rs (deleted in 0c11011c)
// MacOSEngine::new, lines 119-148
let accessibility_enabled = unsafe {
    use core_foundation::dictionary::CFDictionaryRef;

    #[link(name = "ApplicationServices", kind = "framework")]
    unsafe extern "C" {
        fn AXIsProcessTrustedWithOptions(options: CFDictionaryRef) -> bool;
    }

    let check_attr = CFString::new("AXTrustedCheckOptionPrompt");
    let options = CFDictionary::from_CFType_pairs(&[(
        check_attr.as_CFType(),
        CFBoolean::true_value().as_CFType(),
    )])
    .as_concrete_TypeRef();

    AXIsProcessTrustedWithOptions(options)
};

if !accessibility_enabled {
    return Err(AutomationError::PermissionDenied(
        "Accessibility permissions not granted".to_string(),
    ));
}

Ok(Self {
    system_wide: ThreadSafeAXUIElement::system_wide(),
    use_background_apps,
    activate_app,
})

The first time the user runs your binary, macOS pops a prompt asking for accessibility permission. They click OK, then they have to manually toggle your binary on in System Settings, Privacy & Security, Accessibility. They then have to fully quit and relaunch your process, because the trust check is read once and cached for the life of the process.

Pattern 3: the focused-element walk

A thing the system-wide element is good for, that application(pid) can't do, is finding the element under the keyboard cursor right now without knowing which app it is in. You read AXFocusedApplication off the system-wide element to learn which app is foreground, then read AXFocusedUIElement off that app to learn which control inside it has focus.

Two things to know. Both attribute reads return CFType, the Core Foundation top-level dynamic type, not AXUIElement directly; you have to call .downcast::<AXUIElement>() and handle the None case where the attribute existed but did not contain an element. Either read can return kAXErrorNoValue if no app is foreground or the foreground app has no focusable control (think Finder with the desktop selected). That is a normal state, not an error.

// terminator/crates/terminator/src/platforms/macos.rs (deleted in 0c11011c)
// get_focused_element, lines 2386-2410
fn get_focused_element(&self) -> Result<UIElement, AutomationError> {
    let system_wide = AXUIElement::system_wide();
    let focused_app_attr = AXAttribute::new(&CFString::new("AXFocusedApplication"));
    let focused_element_attr = AXAttribute::new(&CFString::new("AXFocusedUIElement"));

    // Step 1: read AXFocusedApplication off system_wide and downcast to AXUIElement
    let focused_app = system_wide.attribute(&focused_app_attr).map_err(|e| {
        AutomationError::ElementNotFound(
            format!("Failed to get focused application: {}", e),
        )
    })?;

    if let Some(app_element) = focused_app.downcast::<AXUIElement>() {
        // Step 2: read AXFocusedUIElement off the app and downcast again
        let focused_element = app_element.attribute(&focused_element_attr).map_err(|e| {
            AutomationError::ElementNotFound(format!(
                "Failed to get focused element within application: {}",
                e
            ))
        })?;

        if let Some(element) = focused_element.downcast::<AXUIElement>() {
            Ok(self.wrap_element(ThreadSafeAXUIElement::new(element)))
        } else {
            Err(AutomationError::ElementNotFound(
                "Focused element attribute did not contain a valid AXUIElement".to_string(),
            ))
        }
    } else {
        Err(AutomationError::ElementNotFound(
            "AXFocusedApplication did not contain a valid AXUIElement".to_string(),
        ))
    }
}

For everything other than the focused-element case, prefer AXUIElement::application(pid). Walking children of AXFocusedApplication is a slow path, only works for whichever app is foreground at the moment of the call, and is racy. The deleted adapter cached one wrapped element per app PID and refreshed by PID enumeration; it used the system-wide element only as a parent reference and as the entry point for focused-element queries.

The error code you will see most often: -25204

The single most common AX error code in real-world code is kAXErrorNoValue (-25204). It does not mean failure; it means the attribute exists for that role but is not currently set, or the element legitimately has no value for it. The system-wide element returns -25204 for almost everything you might call on it directly: .role(), .title(), .position(), .size(). That is by design: the system-wide element exists to hold global attributes (AXFocusedApplication), not to represent a window or control.

Filter -25204 specifically before logging or reporting. Every other -252xx code is a real condition you want to surface:

• -25200 kAXErrorAPIDisabled: accessibility off in System Settings.
• -25201 kAXErrorInvalidUIElement: the element was destroyed or its app died.
• -25204 kAXErrorNoValue: expected on the system-wide root and on legitimate empty attributes.
• -25212 kAXErrorCannotComplete: transient; retry once after a short delay.
• -25214 kAXErrorAttributeUnsupported: this role does not have this attribute; expected during generic walks.

// terminator/crates/terminator/src/platforms/macos.rs (deleted in 0c11011c)
// wrap_element, line 169 — and again at line 1004
if let Err(e) = ax_element.0.role() {
    if let accessibility::Error::Ax(code) = e {
        if code != -25204 {
            // kAXErrorNoValue is expected on the system-wide root and on
            // elements that genuinely have no role; do not warn on those.
            let err_str = error_string(code);
            debug!(
                "Warning: Potentially invalid AXUIElement: {:?} (error: {})",
                e, err_str
            );
        }
    }
}

Things the docs don't warn you about

The first three are non-negotiable on any project that uses the accessibility crate seriously. The fourth one (sandbox) is what makes Mac App Store distribution effectively impossible for any tool built on this API; you ship Developer ID notarized binaries directly to users instead. The fifth one (create-rule) is hidden by the high-level crate, but if you drop down to accessibility-sys and call AXUIElementCreateSystemWide yourself, you must wrap the returned ref under create rule, not get rule. The sixth one (downcast) trips up first-time users of the Core Foundation type system; everything that comes back from an attribute read is a CFType and has to be downcast to the concrete kind you expect.

Why the deleted file is still the reference

On 2025-12-16, Terminator removed crates/terminator/src/platforms/macos.rs (4,368 lines) and crates/terminator/src/platforms/linux.rs (2,962 lines) in commit 0c11011c. The framework is now Windows-only by compile_error! on non-Windows targets; the line lives in crates/terminator/src/platforms/mod.rs.

That doesn't make the deleted file useless to anyone working with the accessibility crate today. The patterns above (Send + Sync newtype, AXIsProcessTrustedWithOptions gate, focused-element walk, kAXErrorNoValue filter) are stable across macOS releases and don't depend on Terminator-specific types. Pull the file with git show 0c11011c~1:crates/terminator/src/platforms/macos.rs and read it as a reference: 130-some distinct AXAttribute strings, the full click strategy ladder, key event composition, monitor enumeration, all using exactly the constructors covered here.

On the active Terminator product side, our focus is the Windows UIA path; that is where the framework ships, where the MCP agent lives, and where the workflow recorder runs. If you are on macOS today and you need a working desktop automation surface that has shipped, you have two honest options: write the Rust against the accessibility crate yourself using the patterns above, or run the Windows MCP server in a VM and drive it from your Mac. We are happy to talk through either route if you want to compare notes; the booking link below is the fastest way to get on a call.