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

# agent-native documentation

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

<div className="relative overflow-hidden bg-gradient-to-br from-[#007AFF] via-[#0A84FF] to-[#5AC8FA] dark:from-[#0A84FF] dark:via-[#007AFF] dark:to-[#005BBB] py-20">
  <div className="max-w-6xl mx-auto px-6 lg:px-8">
    <div className="grid lg:grid-cols-12 gap-12 items-center">
      <div className="lg:col-span-7">
        <h1 className="text-4xl sm:text-5xl lg:text-6xl font-bold text-white mb-6">
          macOS app automation for AI agents
        </h1>

        <p className="text-lg sm:text-xl text-white/90 mb-8 max-w-2xl">
          Control native macOS applications via the Accessibility tree. Like agent-browser, but for desktop apps.
        </p>

        <div className="flex flex-wrap gap-4">
          <a href="/quickstart" className="inline-flex items-center px-6 py-3 rounded-lg bg-white text-[#007AFF] font-semibold hover:bg-gray-100 transition-colors no-underline">
            Get started
          </a>

          <a href="/commands/overview" className="inline-flex items-center px-6 py-3 rounded-lg border-2 border-white/30 bg-white/10 text-white font-semibold hover:bg-white/20 transition-colors no-underline backdrop-blur-sm">
            View commands
          </a>
        </div>
      </div>

      <div className="lg:col-span-5 hidden lg:block">
        <div className="bg-white/10 backdrop-blur-md rounded-2xl p-6 border border-white/20">
          <pre className="text-sm text-white/95 overflow-x-auto">
            {`# List running apps
                        agent-native apps

                        # Open an app
                        agent-native open "System Settings"

                        # Get interactive elements
                        agent-native snapshot "System Settings" -i

                        # Click using ref from snapshot
                        agent-native click @n5

                        # Fill a text field
                        agent-native fill @n3 "Wi-Fi"`}
          </pre>
        </div>
      </div>
    </div>
  </div>
</div>

<div className="mt-16 mb-16 max-w-5xl mx-auto px-6">
  <h2 className="text-3xl font-bold text-gray-900 dark:text-white mb-4">Quick start</h2>

  <p className="text-base text-gray-600 dark:text-gray-400 mb-8">
    Get up and running with agent-native in minutes
  </p>

  <Steps>
    <Step title="Install agent-native">
      Install via Homebrew or build from source:

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

      ```bash From source theme={null}
      git clone https://github.com/ericclemmons/agent-native.git
      cd agent-native
      make install
      ```

      <Note>Requires macOS 13+ (Ventura) and Accessibility permissions for your terminal.</Note>
    </Step>

    <Step title="Grant Accessibility permissions">
      Navigate to **System Settings → Privacy & Security → Accessibility** and add your terminal (Terminal.app, iTerm, or your IDE).

      <Warning>Without Accessibility permissions, agent-native cannot read or control app interfaces.</Warning>
    </Step>

    <Step title="Run your first command">
      Open System Settings and capture its interactive elements:

      ```bash theme={null}
      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.
    </Step>

    <Step title="Interact with elements">
      Use the `@ref` values from the snapshot to interact with elements:

      ```bash theme={null}
      # 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
      ```
    </Step>
  </Steps>
</div>

<div className="mt-16 mb-16 max-w-5xl mx-auto px-6">
  <h2 className="text-3xl font-bold text-gray-900 dark:text-white mb-4">Key features</h2>

  <p className="text-base text-gray-600 dark:text-gray-400 mb-8">
    Everything you need to automate macOS apps with AI agents
  </p>

  <CardGroup cols={3}>
    <Card title="Accessibility tree access" icon="sitemap" href="/concepts/accessibility-tree">
      Read and traverse the macOS Accessibility tree for any running app
    </Card>

    <Card title="Ref-based interaction" icon="hashtag" href="/concepts/refs-and-snapshots">
      Snapshot elements with stable refs, then interact using those refs
    </Card>

    <Card title="Click, fill, type" icon="hand-pointer" href="/commands/interaction">
      Full suite of interaction commands: click, fill, type, check, select, and more
    </Card>

    <Card title="JSON output" icon="code" href="/ai/json-output">
      Structured JSON output for AI agent parsing and decision-making
    </Card>

    <Card title="Keyboard automation" icon="keyboard" href="/commands/keyboard">
      Send keystrokes, modifiers, and shortcuts to any app
    </Card>

    <Card title="Screenshot capture" icon="camera" href="/commands/screenshot">
      Capture app windows for visual context when AX tree is sparse
    </Card>

    <Card title="Wait for elements" icon="clock" href="/commands/wait">
      Wait for elements to appear with configurable timeouts
    </Card>

    <Card title="Electron app support" icon="bolt" href="/guides/electron-apps">
      Work with Slack, Discord, VS Code, and other Electron apps
    </Card>

    <Card title="AI agent ready" icon="robot" href="/ai/overview">
      Built specifically for AI agent workflows with structured output
    </Card>
  </CardGroup>
</div>

<div className="mt-16 mb-16 max-w-5xl mx-auto px-6">
  <h2 className="text-3xl font-bold text-gray-900 dark:text-white mb-4">Explore by topic</h2>

  <p className="text-base text-gray-600 dark:text-gray-400 mb-8">
    Dive into specific areas of agent-native
  </p>

  <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
    <a href="/concepts/workflow" className="group block rounded-2xl border border-gray-200 dark:border-[#27272a] bg-white dark:bg-[#1a1d27] p-6 hover:border-[#007AFF] dark:hover:border-[#0A84FF] transition-colors no-underline">
      <div className="flex items-start gap-4">
        <div className="flex-shrink-0 w-12 h-12 rounded-lg bg-[#007AFF]/10 dark:bg-[#0A84FF]/10 flex items-center justify-center">
          <svg className="w-6 h-6 text-[#007AFF] dark:text-[#0A84FF]" fill="none" stroke="currentColor" viewBox="0 0 24 24">
            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
          </svg>
        </div>

        <div className="flex-1 min-w-0">
          <h3 className="text-lg font-semibold text-gray-900 dark:text-white mb-2 group-hover:text-[#007AFF] dark:group-hover:text-[#0A84FF] transition-colors">
            Core workflow
          </h3>

          <p className="text-sm text-gray-600 dark:text-gray-400 mb-3">
            Learn the snapshot → interact → re-snapshot pattern that powers agent-native automation
          </p>

          <span className="text-sm font-medium text-[#007AFF] dark:text-[#0A84FF] group-hover:underline">
            Learn more →
          </span>
        </div>
      </div>
    </a>

    <a href="/ai/best-practices" className="group block rounded-2xl border border-gray-200 dark:border-[#27272a] bg-white dark:bg-[#1a1d27] p-6 hover:border-[#007AFF] dark:hover:border-[#0A84FF] transition-colors no-underline">
      <div className="flex items-start gap-4">
        <div className="flex-shrink-0 w-12 h-12 rounded-lg bg-[#007AFF]/10 dark:bg-[#0A84FF]/10 flex items-center justify-center">
          <svg className="w-6 h-6 text-[#007AFF] dark:text-[#0A84FF]" fill="none" stroke="currentColor" viewBox="0 0 24 24">
            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z" />
          </svg>
        </div>

        <div className="flex-1 min-w-0">
          <h3 className="text-lg font-semibold text-gray-900 dark:text-white mb-2 group-hover:text-[#007AFF] dark:group-hover:text-[#0A84FF] transition-colors">
            AI integration best practices
          </h3>

          <p className="text-sm text-gray-600 dark:text-gray-400 mb-3">
            How to use agent-native effectively in AI agent workflows with LLMs
          </p>

          <span className="text-sm font-medium text-[#007AFF] dark:text-[#0A84FF] group-hover:underline">
            Learn more →
          </span>
        </div>
      </div>
    </a>

    <a href="/guides/electron-apps" className="group block rounded-2xl border border-gray-200 dark:border-[#27272a] bg-white dark:bg-[#1a1d27] p-6 hover:border-[#007AFF] dark:hover:border-[#0A84FF] transition-colors no-underline">
      <div className="flex items-start gap-4">
        <div className="flex-shrink-0 w-12 h-12 rounded-lg bg-[#007AFF]/10 dark:bg-[#0A84FF]/10 flex items-center justify-center">
          <svg className="w-6 h-6 text-[#007AFF] dark:text-[#0A84FF]" fill="none" stroke="currentColor" viewBox="0 0 24 24">
            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M13 10V3L4 14h7v7l9-11h-7z" />
          </svg>
        </div>

        <div className="flex-1 min-w-0">
          <h3 className="text-lg font-semibold text-gray-900 dark:text-white mb-2 group-hover:text-[#007AFF] dark:group-hover:text-[#0A84FF] transition-colors">
            Automating Electron apps
          </h3>

          <p className="text-sm text-gray-600 dark:text-gray-400 mb-3">
            Special techniques for Slack, Discord, VS Code, and other Electron apps with minimal AX trees
          </p>

          <span className="text-sm font-medium text-[#007AFF] dark:text-[#0A84FF] group-hover:underline">
            Learn more →
          </span>
        </div>
      </div>
    </a>

    <a href="/reference/command-list" className="group block rounded-2xl border border-gray-200 dark:border-[#27272a] bg-white dark:bg-[#1a1d27] p-6 hover:border-[#007AFF] dark:hover:border-[#0A84FF] transition-colors no-underline">
      <div className="flex items-start gap-4">
        <div className="flex-shrink-0 w-12 h-12 rounded-lg bg-[#007AFF]/10 dark:bg-[#0A84FF]/10 flex items-center justify-center">
          <svg className="w-6 h-6 text-[#007AFF] dark:text-[#0A84FF]" fill="none" stroke="currentColor" viewBox="0 0 24 24">
            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z" />
          </svg>
        </div>

        <div className="flex-1 min-w-0">
          <h3 className="text-lg font-semibold text-gray-900 dark:text-white mb-2 group-hover:text-[#007AFF] dark:group-hover:text-[#0A84FF] transition-colors">
            Command reference
          </h3>

          <p className="text-sm text-gray-600 dark:text-gray-400 mb-3">
            Complete list of all agent-native commands with examples and flags
          </p>

          <span className="text-sm font-medium text-[#007AFF] dark:text-[#0A84FF] group-hover:underline">
            Learn more →
          </span>
        </div>
      </div>
    </a>
  </div>
</div>

<div className="mt-20 mb-16 max-w-5xl mx-auto px-6">
  <div className="rounded-2xl border border-gray-200 dark:border-[#27272a] bg-gradient-to-br from-[#007AFF]/5 to-[#5AC8FA]/5 dark:from-[#0A84FF]/10 dark:to-[#007AFF]/10 p-8 lg:p-12">
    <div className="max-w-3xl">
      <h2 className="text-2xl lg:text-3xl font-bold text-gray-900 dark:text-white mb-4">
        Ready to automate macOS apps?
      </h2>

      <p className="text-base text-gray-600 dark:text-gray-400 mb-6">
        Install agent-native and start building AI agents that can control any macOS application.
      </p>

      <a href="/installation" className="inline-flex items-center px-6 py-3 rounded-lg bg-[#007AFF] dark:bg-[#0A84FF] text-white font-semibold hover:bg-[#0051D5] dark:hover:bg-[#007AFF] transition-colors no-underline">
        Install now
      </a>
    </div>
  </div>
</div>