AXorcist 🧙‍♂️ - The power of Swift compels your UI to obey!

Swift wrapper for macOS Accessibility—chainable, fuzzy-matched queries
that read, click, and inspect any UI. The dark arts meet modern Swift!

Platform target: macOS 14.0 and later. AXorcist sits on top of the Accessibility APIs that only ship on macOS, so CI and releases intentionally stay macOS-only.

AXorcist harnesses the supernatural powers of macOS Accessibility APIs to give you mystical control over any application's interface. Whether you're automating workflows, testing applications, or building assistive technologies, AXorcist provides the incantations you need to make UI elements bend to your will.

Overview

AXorcist enables developers to create sophisticated automation tools, testing frameworks, and accessibility utilities by providing:

Type-safe API: Compile-time safety for accessibility attributes and operations
Modern Swift Patterns: Async/await, structured concurrency, and error handling
Comprehensive Command System: Query, action, observation, and batch operations
Element Management: Efficient UI element discovery and interaction
Permission Handling: Streamlined accessibility permission workflows

This document provides a comprehensive overview of all AXorcist classes and their usage patterns. For interactive API documentation, run ../view-docs.sh to open the DocC archives.

Core Classes Reference

AXorcist (Main Class)

The central orchestrator for all accessibility operations.

@MainActor
public class AXorcist {
    static let shared = AXorcist()
    public func runCommand(_ commandEnvelope: AXCommandEnvelope) -> AXResponse
}

Key Features:

Singleton pattern for consistent state management
Command-based architecture for all operations
MainActor isolation for thread safety
Comprehensive error handling

Usage Example:

import AXorcist

let axorcist = AXorcist.shared
let query = QueryCommand(
    appIdentifier: "Safari",
    locator: Locator(criteria: [Criterion(attribute: "AXRole", value: "AXButton")]))
let command = AXCommandEnvelope(
    commandID: "find-button",
    command: .query(query)
)
let response = axorcist.runCommand(command)

Element

Swift wrapper around AXUIElement providing modern API patterns.

public struct Element: Equatable, Hashable {
    public let underlyingElement: AXUIElement
    public var attributes: [String: AttributeValue]?
    public var prefetchedChildren: [Element]?
    public var actions: [String]?
}

Key Features:

Type-safe property access with computed properties
Automatic value conversion between CF and Swift types
Hierarchy navigation with caching support
Action execution with error handling
Batch attribute fetching for performance

Common Operations:

// Create element wrapper
let element = Element(axUIElement)

// Access properties safely
let title = element.title()
let role = element.role()
let isEnabled = element.isEnabled()

// Perform actions
try element.performAction(.press)
_ = element.setValue("Hello World", forAttribute: "AXValue")

// Navigate hierarchy
let children = element.children()
let parent = element.parent()

AXPermissionHelpers

Modern async/await API for accessibility permissions.

public struct AXPermissionHelpers {
    static func hasAccessibilityPermissions() -> Bool
    static func requestPermissions() async -> Bool
    static func permissionChanges(interval: TimeInterval = 1.0) -> AsyncStream<Bool>
    static func isSandboxed() -> Bool
}

Key Features:

Async/await permission handling
Real-time permission monitoring with AsyncStream
Sandbox detection for permission strategy
Non-blocking permission requests

Usage Patterns:

// Check current status
let hasPermissions = AXPermissionHelpers.hasAccessibilityPermissions()

// Request permissions asynchronously
let granted = await AXPermissionHelpers.requestPermissions()

// Monitor permission changes
for await hasPermissions in AXPermissionHelpers.permissionChanges() {
    if hasPermissions {
        print("Permissions granted!")
        // Enable accessibility features
    } else {
        print("Permissions revoked!")
        // Disable accessibility features
    }
}

Features

🔍 Powerful Search: Find UI elements using multiple criteria with flexible matching
🎯 Precise Navigation: Navigate UI hierarchies with path-based locators
🎬 Actions: Perform clicks, set values, and trigger UI interactions
👁️ Observation: Monitor UI changes in real-time with notifications
🚀 Batch Operations: Execute multiple commands efficiently
📊 Rich Attributes: Access all accessibility attributes and computed properties
🔧 CLI Tool: Full command-line interface for scripting and automation
📝 Comprehensive Logging: Debug support with detailed operation logs

Installation

Swift Package Manager

Add to your Package.swift:

dependencies: [
    .package(url: "https://github.com/openclaw/AXorcist.git", from: "0.1.6")
]

Command Line Tool

Install the signed, notarized universal CLI with Homebrew:

brew install openclaw/tap/axorc

Or build and install it from source:

swift build -c release --product axorc
install -m 755 .build/release/axorc /usr/local/bin/axorc

Run axorc permissions after installation. macOS will need Accessibility permission for inspection and automation.

Maintainers: see docs/releasing.md for the artifact and tap workflow.

Quick Start

Swift API

import AXorcist

// Initialize AXorcist
let axorcist = AXorcist()

// Create a query command
let query = QueryCommand(
    appIdentifier: "com.apple.TextEdit",
    locator: Locator(criteria: [
        Criterion(attribute: "AXRole", value: "AXTextArea")
    ]),
    attributesToReturn: ["AXValue", "AXRole"]
)

// Execute the command
let response = axorcist.runCommand(AXCommandEnvelope(
    commandID: "query-1",
    command: .query(query)
))

Command Line

# Print a shallow accessibility tree
axorc tree --app Safari --depth 3

# Find the Back button
axorc find --app Safari --role AXButton --title Back

# Use the full JSON protocol for actions and advanced queries
echo '{"command_id":"back","command":"performAction","application":"Safari","locator":{"criteria":[{"attribute":"AXTitle","value":"Back"}]},"action_name":"AXPress"}' | axorc raw --stdin

Element Search and Matching

Matching Types

AXorcist supports multiple matching strategies:

exact - Exact string match (default)
contains - Case-insensitive substring match
regex - Regular expression match
containsAny - Matches if any comma-separated value is contained
prefix - String starts with the expected value
suffix - String ends with the expected value

Searchable Attributes

Core Attributes

role / AXRole - Element's role (e.g., "AXButton", "AXWindow")
subrole / AXSubrole - Additional role information
identifier / id / AXIdentifier - Developer-assigned unique ID
title / AXTitle - Element's title
value / AXValue - Element's value
description / AXDescription - Detailed description
help / AXHelp - Tooltip/help text
placeholder / AXPlaceholderValue - Placeholder text

State Attributes

enabled / AXEnabled - Is element enabled?
focused / AXFocused - Is element focused?
hidden / AXHidden - Is element hidden?
busy / AXElementBusy - Is element busy?

Special Attributes

pid - Process ID (exact match only)
domclasslist / AXDOMClassList - Web element classes
domid / AXDOMIdentifier - DOM element ID
computedname / name - Computed accessible name

Search Examples

Find button by exact title

{
  "criteria": [
    {"attribute": "role", "value": "AXButton"},
    {"attribute": "title", "value": "Submit"}
  ]
}

Find text field containing "email"

{
  "criteria": [
    {"attribute": "role", "value": "AXTextField"},
    {"attribute": "title", "value": "email", "match_type": "contains"}
  ]
}

Find element by multiple classes (web content)

{
  "criteria": [
    {"attribute": "domclasslist", "value": "btn-primary", "match_type": "contains"}
  ]
}

Using OR logic

{
  "criteria": [
    {"attribute": "title", "value": "Save"},
    {"attribute": "title", "value": "Submit"},
    {"attribute": "title", "value": "OK"}
  ],
  "matchAll": false
}

Path Navigation

Navigate through UI hierarchies with path hints:

{
  "path_from_root": [
    {"attribute": "role", "value": "AXWindow", "depth": 1},
    {"attribute": "identifier", "value": "main-content", "depth": 3},
    {"attribute": "role", "value": "AXButton"}
  ]
}

Each path component supports:

attribute - What to match
value - Expected value
depth - Max search depth for this step (default: 3)
match_type - How to match (default: exact)

Available Commands

1. Query

Find elements and retrieve their attributes.

{
  "command_id": "find-text-area",
  "command": "query",
  "application": "com.apple.TextEdit",
  "locator": {
    "criteria": [{"attribute": "AXRole", "value": "AXTextArea"}]
  },
  "attributes": ["AXValue", "AXRole", "AXTitle"],
  "max_depth": 10
}

2. Perform Action

Execute actions on elements.

{
  "command_id": "press-back",
  "command": "performAction",
  "application": "Safari",
  "locator": {
    "criteria": [{"attribute": "AXTitle", "value": "Back"}]
  },
  "action_name": "AXPress"
}

3. Get Focused Element

Retrieve the currently focused element.

{
  "command_id": "focused-element",
  "command": "getFocusedElement",
  "attributes": ["AXRole", "AXTitle", "AXValue"]
}

4. Get Element at Point

Find element at specific screen coordinates.

{
  "command_id": "element-at-point",
  "command": "getElementAtPoint",
  "point": [500, 300],
  "attributes": ["AXRole", "AXTitle"]
}

5. Batch Commands

Execute multiple commands in sequence.

{
  "command_id": "inspect-and-fill",
  "command": "batch",
  "sub_commands": [
    {
      "command_id": "find-text-area",
      "command": "query",
      "application": "TextEdit",
      "locator": {"criteria": [{"attribute": "AXRole", "value": "AXTextArea"}]}
    },
    {
      "command_id": "fill-text-area",
      "command": "performAction",
      "application": "TextEdit",
      "locator": {"criteria": [{"attribute": "AXRole", "value": "AXTextArea"}]},
      "action_name": "AXSetValue",
      "action_value": "Hello, World!"
    }
  ]
}

6. Observe Notifications

Monitor UI changes in real-time.

{
  "command_id": "watch-text-edit",
  "command": "observe",
  "application": "com.apple.TextEdit",
  "notifications": ["AXValueChanged", "AXFocusedUIElementChanged"],
  "include_element_details": ["AXRole", "AXTitle", "AXValue"],
  "watch_children": false
}

7. Collect All

Recursively collect all elements.

{
  "command_id": "collect-buttons",
  "command": "collectAll",
  "application": "Safari",
  "attributes": ["AXRole", "AXTitle"],
  "max_depth": 5,
  "filter_criteria": {"AXRole": "AXButton"}
}

Actions

Available actions to perform on elements:

AXPress - Click/activate an element
AXIncrement - Increment value (sliders, steppers)
AXDecrement - Decrement value
AXConfirm - Confirm action
AXCancel - Cancel action
AXShowMenu - Show context menu
AXPick - Pick/select element
AXRaise - Bring element to front
AXSetValue - Set value (for text fields)

Setting Text Values

{
  "command_id": "replace-text",
  "command": "performAction",
  "application": "TextEdit",
  "locator": {"criteria": [{"attribute": "AXRole", "value": "AXTextArea"}]},
  "action_name": "AXSetValue",
  "action_value": "New text content"
}

Notifications and Observing

Monitor UI changes with these notifications:

AXFocusedUIElementChanged - Focus changes
AXValueChanged - Value changes
AXUIElementDestroyed - Element destruction
AXWindowCreated - Window creation
AXWindowResized - Window resizing
AXTitleChanged - Title changes
AXSelectedTextChanged - Text selection changes
AXLayoutChanged - Layout updates

Observer Example

{
  "command_id": "watch-text",
  "command": "observe",
  "application": "TextEdit",
  "notifications": ["AXValueChanged", "AXFocusedUIElementChanged"],
  "locator": {"criteria": [{"attribute": "AXRole", "value": "AXTextArea"}]},
  "include_element_details": ["AXRole", "AXTitle", "AXValue"]
}

Command-Line Usage

axorc has human-readable inspection commands and a stable JSON mode for scripts and advanced automation.

Inspect Applications

# Check permission and recovery instructions
axorc permissions

# Print a hierarchy; use a bundle identifier when names are ambiguous
axorc tree --app com.apple.dock --depth 3

# Limit a tree to one role and emit JSON for scripts
axorc tree --app com.apple.dock --role AXDockItem --json

# Find one element with exact matching
axorc find --app Safari --role AXButton --title Back

# Use case-insensitive substring matching
axorc find --app Safari --title address --contains

Run axorc --help or axorc help find for the complete terminal reference. Human-readable output goes to stdout, diagnostics go to stderr, and failures return nonzero exit codes.

JSON Protocol

Every JSON command requires command_id and command. Input can come from standard input, a file, an argument, or the legacy root-level syntax:

# Standard input
echo '{
  "command_id": "enabled-button",
  "command": "query",
  "application": "Safari",
  "locator": {
    "criteria": [
      {"attribute": "AXRole", "value": "AXButton"},
      {"attribute": "AXEnabled", "value": "true"}
    ]
  }
}' | axorc raw --stdin

# File
axorc raw --file command.json

# Argument
axorc raw --json '{"command_id":"health","command":"ping"}'

# Action using path navigation
echo '{
  "command_id": "press-back",
  "command": "performAction",
  "application": "com.apple.Safari",
  "locator": {
    "path_from_root": [
      {"attribute": "AXRole", "value": "AXWindow"},
      {"attribute": "AXIdentifier", "value": "toolbar"}
    ],
    "criteria": [{"attribute": "AXTitle", "value": "Back"}]
  },
  "action_name": "AXPress"
}' | axorc raw --stdin

Existing invocations such as axorc --stdin and axorc '{...}' remain supported. Prefer the explicit raw subcommand in new scripts.

Advanced Examples

Complex Search with Path Navigation

{
  "command_id": "find-submit",
  "command": "query",
  "application": "com.apple.Safari",
  "locator": {
    "path_from_root": [
      {"attribute": "AXRole", "value": "AXWindow", "depth": 1},
      {"attribute": "AXRole", "value": "AXWebArea", "depth": 5}
    ],
    "criteria": [
      {"attribute": "AXRole", "value": "AXButton"},
      {"attribute": "AXDOMClassList", "value": "submit-button primary", "match_type": "contains"}
    ]
  },
  "attributes": ["AXTitle", "AXValue", "AXEnabled", "AXPosition", "AXSize"]
}

Automated Form Filling

{
  "command_id": "fill-form",
  "command": "batch",
  "sub_commands": [
    {
      "command_id": "fill-email",
      "command": "performAction",
      "application": "Safari",
      "locator": {
        "criteria": [
          {"attribute": "AXRole", "value": "AXTextField"},
          {"attribute": "AXPlaceholderValue", "value": "Email", "match_type": "contains"}
        ]
      },
      "action_name": "AXSetValue",
      "action_value": "user@example.com"
    },
    {
      "command_id": "fill-password",
      "command": "performAction",
      "application": "Safari",
      "locator": {
        "criteria": [
          {"attribute": "AXRole", "value": "AXTextField"},
          {"attribute": "AXPlaceholderValue", "value": "Password", "match_type": "contains"}
        ]
      },
      "action_name": "AXSetValue",
      "action_value": "example-value"
    },
    {
      "command_id": "submit-form",
      "command": "performAction",
      "application": "Safari",
      "locator": {
        "criteria": [
          {"attribute": "AXRole", "value": "AXButton"},
          {"attribute": "AXTitle", "value": "Sign In", "match_type": "contains"}
        ]
      },
      "action_name": "AXPress"
    }
  ]
}

Monitoring Text Changes

{
  "command_id": "watch-text",
  "command": "observe",
  "application": "com.apple.TextEdit",
  "notifications": ["AXValueChanged", "AXSelectedTextChanged"],
  "locator": {
    "criteria": [{"attribute": "AXRole", "value": "AXTextArea"}]
  },
  "include_element_details": ["AXRole", "AXTitle", "AXValue"],
  "watch_children": true
}

Architecture

Core Components

AXorcist - Main orchestrator class
Element - Wrapper around AXUIElement with convenience methods
ElementSearch - Tree traversal and matching engine
AXElementMatcher - Criteria matching logic
PathNavigator - Hierarchical navigation
AXObserverCenter - Notification management

Thread Safety

All operations are MainActor-isolated for thread safety when interacting with the Accessibility API.

Performance Optimizations

Early termination on first match
Depth-limited searches
Efficient tree traversal with visitor pattern
Caching of frequently accessed attributes

Troubleshooting

Permission Issues

Check Accessibility permission and print recovery instructions:

axorc permissions

Finding Elements

Use the debug flag to see detailed search logs:

axorc raw --file command.json --debug

Common Issues

Element not found: Try broader criteria or increase search depth
Action failed: Ensure element is enabled and supports the action
Observer not working: Check notification names and app identifier

Debug Mode

Enable debug logging in commands:

{
  "command_id": "debug-query",
  "command": "query",
  "debug_logging": true,
  ...
}

License

AXorcist is released under the MIT License. See LICENSE for details.

Contributing

Please follow the main Peekaboo contributing guidelines and open pull requests against this repository when proposing AXorcist changes.

Coverage

Date	Command	Scope	Line Coverage
2025-11-13	`swift test --package-path AXorcist --enable-code-coverage --filter AXorcistTests.PingIntegrationTests`	Ping integration suite only	2.39 %
2025-11-12	`swift test --package-path AXorcist --enable-code-coverage --filter AXorcistTests.PingIntegrationTests`	Ping integration suite only	2.39 %

Only the PingIntegrationTests subset currently runs in this headless environment; the automation-tagged suites require interactive UI access. Coverage is produced with xcrun llvm-cov report AXorcist/.build/debug/axPackagePackageTests.xctest/Contents/MacOS/axPackagePackageTests -instr-profile AXorcist/.build/debug/codecov/default.profdata.

Name		Name	Last commit message	Last commit date
Latest commit History 150 Commits
.github/workflows		.github/workflows
.vscode		.vscode
Examples		Examples
Sources		Sources
Tests/AXorcistTests		Tests/AXorcistTests
assets		assets
docs		docs
packaging/homebrew		packaging/homebrew
scripts		scripts
.gitignore		.gitignore
.swiftformat		.swiftformat
.swiftlint.yml		.swiftlint.yml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
Package.resolved		Package.resolved
Package.swift		Package.swift
README.md		README.md
axorc_runner.sh		axorc_runner.sh
run_axorc_with_json_content.sh		run_axorc_with_json_content.sh
run_tests.sh		run_tests.sh

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

AXorcist 🧙‍♂️ - The power of Swift compels your UI to obey!

Overview

Core Classes Reference

AXorcist (Main Class)

Element

AXPermissionHelpers

Table of Contents

Features

Installation

Swift Package Manager

Command Line Tool

Quick Start

Swift API

Command Line

Element Search and Matching

Matching Types

Searchable Attributes

Core Attributes

State Attributes

Special Attributes

Search Examples

Find button by exact title

Find text field containing "email"

Find element by multiple classes (web content)

Using OR logic

Path Navigation

Available Commands

1. Query

2. Perform Action

3. Get Focused Element

4. Get Element at Point

5. Batch Commands

6. Observe Notifications

7. Collect All

Actions

Setting Text Values

Notifications and Observing

Observer Example

Command-Line Usage

Inspect Applications

JSON Protocol

Advanced Examples

Complex Search with Path Navigation

Automated Form Filling

Monitoring Text Changes

Architecture

Core Components

Thread Safety

Performance Optimizations

Troubleshooting

Permission Issues

Finding Elements

Common Issues

Debug Mode

License

Contributing

Coverage

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 6

Uh oh!

Contributors

Uh oh!

Languages