Skip to main content
agent-native is distributed via Homebrew or can be built from source. After installation, you’ll need to grant Accessibility permissions to your terminal.

​
Prerequisites

macOS 13+ (Ventura) is required. agent-native uses modern Accessibility APIs that are only available on macOS 13 and later.
Before installing, ensure you have:
  • macOS 13 (Ventura) or later
  • Terminal access (Terminal.app, iTerm2, or your preferred terminal emulator)
  • Admin privileges to grant Accessibility permissions

​
Install via Homebrew

The simplest installation method is through Homebrew: 
brew install ericclemmons/tap/agent-native
This installs the pre-compiled binary and adds agent-native to your PATH automatically.

​
Build from source

If you prefer to build from source or want to contribute:
1

Clone the repository

git clone https://github.com/ericclemmons/agent-native.git
cd agent-native
2

Build and install

make install
This compiles the Swift code and installs the binary to /usr/local/bin/agent-native
Building from source requires Xcode Command Line Tools. Install with: xcode-select --install

​
Grant Accessibility permissions

This is the most critical step. Without Accessibility permissions, agent-native cannot read or interact with application UI elements.
1

Open System Settings

Navigate to System Settings > Privacy & Security > Accessibility
You can quickly open this with Spotlight: Press Cmd+Space, type “accessibility”, and select the Privacy & Security preference pane.
2

Click the lock to make changes

Click the lock icon in the bottom-left corner and authenticate with your password or Touch ID
3

Add your terminal application

Click the + button and navigate to your terminal:
  • Terminal.app: /Applications/Utilities/Terminal.app
  • iTerm2: /Applications/iTerm.app
  • VS Code integrated terminal: /Applications/Visual Studio Code.app
  • Warp: /Applications/Warp.app
Select your terminal and click Open
4

Enable the checkbox

Ensure the checkbox next to your terminal application is checked (enabled)
If you use multiple terminals or IDEs with integrated terminals, you’ll need to grant permissions to each one individually.

​
Verify installation

Confirm that agent-native is installed correctly and has the necessary permissions: 
agent-native --version
Expected output:
0.1.4

​
Troubleshooting

This means your terminal doesn’t have Accessibility permissions. Follow the Grant Accessibility permissions steps above.After granting permissions, you may need to:
  1. Quit and restart your terminal completely
  2. In some cases, log out and log back in to macOS
The binary isn’t in your PATH. Try:
  1. Homebrew: Run brew doctor to check for PATH issues
  2. From source: Verify the binary exists at /usr/local/bin/agent-native
  3. Add to PATH manually: export PATH="/usr/local/bin:$PATH" in your ~/.zshrc or ~/.bash_profile
agent-native uses fuzzy matching to find apps by name. Ensure:
  1. The app is actually running (check with agent-native apps)
  2. You’re using the correct app name (e.g., “System Settings” not “System Preferences” on macOS 13+)
  3. Try using the bundle ID instead: agent-native open com.apple.systempreferences
Some apps have restricted Accessibility APIs or require additional permissions:
  1. Try running the command with sudo (not recommended for regular use)
  2. Check if the app itself requires additional security permissions
  3. Some system apps may have limited interaction capabilities

​
Next steps

Quick start tutorial

Learn the core workflow with a hands-on example using System Settings

Build docs developers (and LLMs) love

Get started for freeTalk to us