> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ericclemmons/agent-native/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Control macOS native apps via the Accessibility tree - like agent-browser, but for the desktop

**agent-native** gives AI agents structured control over macOS native applications through the Accessibility (AX) tree.

## What is agent-native?

agent-native is a macOS CLI tool that exposes native application UI elements to AI agents and automation scripts. Inspired by [agent-browser](https://github.com/vercel-labs/agent-browser) from Vercel Labs, it brings the same level of structured control to desktop apps that agent-browser provides for web pages.

<Info>
  Where agent-browser uses Chrome DevTools Protocol (CDP) and the DOM for web automation, agent-native uses macOS Accessibility APIs and the AX tree for native app automation.
</Info>

## Key capabilities

<CardGroup cols={2}>
  <Card title="Discovery" icon="binoculars">
    List running apps, open applications, and explore their UI structure through the Accessibility tree
  </Card>

  <Card title="Snapshot" icon="camera">
    Capture interactive elements with persistent references (@n1, @n2) for reliable interaction
  </Card>

  <Card title="Interaction" icon="hand-pointer">
    Click buttons, fill text fields, check toggles, select from dropdowns using simple commands
  </Card>

  <Card title="State inspection" icon="magnifying-glass">
    Read text, check element state, get attributes, and verify UI conditions
  </Card>
</CardGroup>

## Core workflow

The typical agent-native workflow follows a simple pattern:

<Steps>
  <Step title="Launch the app">
    ```bash theme={null}
    agent-native open "System Settings"
    ```
  </Step>

  <Step title="Take a snapshot">
    ```bash theme={null}
    agent-native snapshot "System Settings" -i
    ```

    This generates persistent references (like `@n5`, `@n3`) for interactive elements
  </Step>

  <Step title="Interact using refs">
    ```bash theme={null}
    agent-native click @n5
    agent-native fill @n3 "Wi-Fi"
    ```
  </Step>

  <Step title="Re-snapshot after changes">
    When the UI changes (new dialog, different pane), take another snapshot to get fresh references
  </Step>
</Steps>

## When to use agent-native

agent-native is ideal for:

* **AI agent automation**: Give LLMs structured access to desktop apps with JSON output
* **GUI testing**: Automate macOS app testing through the Accessibility APIs
* **Desktop workflows**: Chain together actions across multiple native applications
* **System administration**: Automate System Settings and other macOS utilities
* **Accessibility tooling**: Build tools that inspect and interact with app UI elements

<Warning>
  agent-native requires **macOS 13+ (Ventura)** and **Accessibility permissions** for your terminal. See the [installation guide](/installation) for setup instructions.
</Warning>

## Agent mode

Every command supports `--json` output for structured data suitable for LLM tool use:

```bash theme={null}
agent-native snapshot "System Settings" -i --json | jq '.[0].ref'
agent-native get text @n1 --json
agent-native is enabled @n5 --json
```

## Next steps

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/installation">
    Install via Homebrew or build from source
  </Card>

  <Card title="Quick start" icon="rocket" href="/quickstart">
    Complete tutorial from installation to first automation
  </Card>
</CardGroup>