Skip to main content

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.

macOS app automation for AI agents

Control native macOS applications via the Accessibility tree. Like agent-browser, but for desktop apps.

Get startedView commands

Quick start

Get up and running with agent-native in minutes

1

Install agent-native

Install via Homebrew or build from source:
Homebrew
brew install ericclemmons/tap/agent-native
From source
git clone https://github.com/ericclemmons/agent-native.git
cd agent-native
make install
Requires macOS 13+ (Ventura) and Accessibility permissions for your terminal.
2

Grant Accessibility permissions

Navigate to System Settings → Privacy & Security → Accessibility and add your terminal (Terminal.app, iTerm, or your IDE).
Without Accessibility permissions, agent-native cannot read or control app interfaces.
3

Run your first command

Open System Settings and capture its interactive elements:
agent-native open "System Settings"
agent-native snapshot "System Settings" -i
You’ll see a tree of interactive elements with @ref identifiers like @n1, @n2, etc.
4

Interact with elements

Use the @ref values from the snapshot to interact with elements:
# Click a button
agent-native click @n5

# Fill a search field
agent-native fill @n3 "Wi-Fi"

# Check if an element is enabled
agent-native is enabled @n7

Key features

Everything you need to automate macOS apps with AI agents

Accessibility tree access

Read and traverse the macOS Accessibility tree for any running app

Ref-based interaction

Snapshot elements with stable refs, then interact using those refs

Click, fill, type

Full suite of interaction commands: click, fill, type, check, select, and more

JSON output

Structured JSON output for AI agent parsing and decision-making

Keyboard automation

Send keystrokes, modifiers, and shortcuts to any app

Screenshot capture

Capture app windows for visual context when AX tree is sparse

Wait for elements

Wait for elements to appear with configurable timeouts

Electron app support

Work with Slack, Discord, VS Code, and other Electron apps

AI agent ready

Built specifically for AI agent workflows with structured output

Explore by topic

Dive into specific areas of agent-native

Core workflow

Learn the snapshot → interact → re-snapshot pattern that powers agent-native automation

Learn more →

AI integration best practices

How to use agent-native effectively in AI agent workflows with LLMs

Learn more →

Automating Electron apps

Special techniques for Slack, Discord, VS Code, and other Electron apps with minimal AX trees

Learn more →

Command reference

Complete list of all agent-native commands with examples and flags

Learn more →

Ready to automate macOS apps?

Install agent-native and start building AI agents that can control any macOS application.

Install now