Getting started

This section takes you from nothing installed to an AI agent that can see your screen, speak to you, and act on your Mac through its accessibility layer — Accessibility tree first, pixels only as a fallback. It is written for two readers at once: the person who will actually use the result (often someone blind or low-vision, frequently working with the display off) and the person doing the install (which today is a technical, hands-on step — see the warning below).

If you already know what Autonomy is and why it exists, skip ahead to Install. If you want the conceptual grounding first, read What is Autonomy and MCP-native architecture — this section assumes neither, but links back to both where it helps.

The end state: a macOS app is running, Accessibility and Screen Recording are granted, a7y-cli doctor is green, an MCP-native agent (Claude Code by default) is connected and can see roughly 170 Autonomy tools, and you’ve watched it complete one small, real, verified task — driven entirely by voice and conversation, no screen required.

The install path in this section is developer-oriented. There is no signed, notarized, one-click download yet, and the source repository is not public. You’ll build and install the app from a local checkout. A notarized end-user download is planned but not live — this guide won’t pretend otherwise.

Who this is for

Reader	What they get from this section
A blind or low-vision user	The full path from a fresh Mac to an agent that narrates and acts for you, screen off. Every step after Grant permissions can be driven by voice.
A sighted helper setting it up for someone else	The concrete, copy-pasteable commands for the parts that still need a keyboard and a sighted eye — mainly the app build/install step.
A developer or agent-host builder	The exact scripts and MCP wiring Autonomy uses today, so you can reproduce or extend it.

The map

Five steps, each gating the next — you cannot usefully skip ahead:


 1. Install          build + install the macOS app (stable identity)
       |
       v
 2. Grant permissions   Accessibility + Screen Recording (TCC prompts)
       |
       v
 3. Run the doctor      a7y-cli doctor: 4 phases, each gates the next
       |
       v
 4. Connect an agent    Claude Code (or Codex, or any MCP client) -> a7y-mcp
       |
       v
 5. First screen-off task   ask it to do something, verify it happened

This mirrors the runtime’s own gating logic: the doctor won’t tell you the daemon is healthy until permissions are granted, and an agent has nothing to connect to until the app — and its one daemon — is running. Each page in this section corresponds to one step:

Install — build the app, install it to /Applications with a stable permission identity.
Grant permissions — Accessibility and Screen Recording, why each matters, how to verify both actually took.
Run the doctor — the phased readiness check that tells you exactly what to fix, in order.
Connect your first agent — wire Claude Code to the Autonomy MCP daemon and confirm the tools are visible.
Your first screen-off task — a small, real, voice-driven task with verification after every step.

A mental model for the whole path

Autonomy is not an agent — it’s the layer between an agent’s intent and your Mac’s real assistive-technology state. Every step in this section exists to stand up one link in that chain:


 agent host (Claude Code)  --MCP-->  Autonomy daemon  --AX/TTS/Browser-->  your Mac
       ^                                    ^
       |                                    |
  step 4 connects this              steps 1-3 build, install, and
                                     verify this exists and is healthy

Nothing in step 4 or 5 works if steps 1–3 were skipped or only half-done — that’s the entire reason doctor exists: to say precisely which link is broken before you go looking for one yourself.

If something doesn’t match what you see

Source drifts faster than docs. If a command in this section doesn’t exist or behaves differently, trust a7y-cli doctor’s own output and Troubleshooting over guesswork, and treat any claim about exact macOS permission-dialog wording as approximate rather than pixel-accurate.

Start with Install.