> ## 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.

# Installation

> Install agent-native on macOS and configure Accessibility permissions

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

<Warning>
  **macOS 13+ (Ventura) is required.** agent-native uses modern Accessibility APIs that are only available on macOS 13 and later.
</Warning>

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:

```bash theme={null}
brew install ericclemmons/tap/agent-native
```

<Tip>
  This installs the pre-compiled binary and adds `agent-native` to your PATH automatically.
</Tip>

## Build from source

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

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/ericclemmons/agent-native.git
    cd agent-native
    ```
  </Step>

  <Step title="Build and install">
    ```bash theme={null}
    make install
    ```

    This compiles the Swift code and installs the binary to `/usr/local/bin/agent-native`
  </Step>
</Steps>

<Note>
  Building from source requires Xcode Command Line Tools. Install with: `xcode-select --install`
</Note>

## Grant Accessibility permissions

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

<Steps>
  <Step title="Open System Settings">
    Navigate to **System Settings > Privacy & Security > Accessibility**

    <Tip>
      You can quickly open this with Spotlight: Press `Cmd+Space`, type "accessibility", and select the Privacy & Security preference pane.
    </Tip>
  </Step>

  <Step title="Click the lock to make changes">
    Click the lock icon in the bottom-left corner and authenticate with your password or Touch ID
  </Step>

  <Step title="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**
  </Step>

  <Step title="Enable the checkbox">
    Ensure the checkbox next to your terminal application is **checked** (enabled)
  </Step>
</Steps>

<Warning>
  If you use multiple terminals or IDEs with integrated terminals, you'll need to grant permissions to **each one individually**.
</Warning>

## Verify installation

Confirm that agent-native is installed correctly and has the necessary permissions:

<Tabs>
  <Tab title="Check version">
    ```bash theme={null}
    agent-native --version
    ```

    Expected output:

    ```
    0.1.4
    ```
  </Tab>

  <Tab title="List running apps">
    ```bash theme={null}
    agent-native apps
    ```

    You should see a list of currently running GUI applications. If you get an access denied error, revisit the Accessibility permissions step.
  </Tab>

  <Tab title="Test with JSON output">
    ```bash theme={null}
    agent-native apps --format json
    ```

    This returns structured JSON suitable for agent consumption:

    ```json theme={null}
    [
      {
        "name": "Finder",
        "bundleId": "com.apple.finder",
        "pid": 1234,
        "isActive": true,
        "isHidden": false
      }
    ]
    ```
  </Tab>
</Tabs>

## Troubleshooting

<Accordion title="Error: Accessibility access denied">
  This means your terminal doesn't have Accessibility permissions. Follow the [Grant Accessibility permissions](#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
</Accordion>

<Accordion title="Command not found: agent-native">
  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`
</Accordion>

<Accordion title="App not found errors when running commands">
  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`
</Accordion>

<Accordion title="Commands work but can't interact with elements">
  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
</Accordion>

## Next steps

<Card title="Quick start tutorial" icon="rocket" href="/quickstart">
  Learn the core workflow with a hands-on example using System Settings
</Card>