Grant permissions

Autonomy asks macOS for two permissions: Accessibility and Screen Recording. Both are gates macOS itself enforces through Privacy & Security — Autonomy can’t act on your screen or read its structure without them, no matter how the agent connected to it is configured. This page explains why each one exists, how to grant it, and — because “I clicked yes” and “it actually took” aren’t always the same thing — how to check.

If you haven’t installed the app yet, start at Install first; permissions attach to that specific app bundle.

Why two permissions, and why they’re not optional

Accessibility is what lets Autonomy read the accessibility tree (roles, labels, values, focus, required/disabled state) and act through it — clicking a button by its semantic identity instead of guessing screen coordinates. This is the permission the accessibility model depends on for everything: without it, an agent has no reliable way to know what’s actually on your screen.

Screen Recording backs the visual-verification and vision fallback paths — confirming something rendered correctly, reading a value the accessibility tree doesn’t expose well, and the browser lane’s screenshot-based checks. AX-only review (reading forms, labels, and structure) can still work without it, but anything that needs to see the screen cannot.

Autonomy asks for both up front rather than lazily, because a mid-task permission prompt is exactly the kind of silent, unannounced interruption the product’s accessibility-first design is trying to avoid.

Granting them

The setup wizard that opens the first time you launch autonomy (a7y).app walks you through a Permissions page as one of its seven steps (Welcome → Choose your agent → Sign in → Permissions → How you work → What’s connected → You’re set). Each row triggers the real system prompt when you choose to grant it — the wizard doesn’t pre-answer anything on your behalf.

You can also grant, or double-check, both manually:

Open the Privacy & Security panes

System Settings → Privacy & Security → Accessibility, and System Settings → Privacy & Security → Screen Recording — labeled “Screen & System Audio Recording” on macOS 15 (Sequoia) and later. If you’d rather skip the navigation, jump straight there:


open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"

Toggle the app on

Modern System Settings (macOS 13 Ventura and later) lists each app with a per-app toggle — there’s no ”+” button here. Find autonomy (a7y) in each pane and switch its toggle on. If it isn’t listed yet, it appears once it first requests the permission, alongside an “Open System Settings” prompt.

Restart if Screen Recording needs it

Screen Recording requires quitting and reopening the app — the grant doesn’t take effect until you do, and macOS itself prompts with a “Quit & Reopen” button right after you toggle it on. Treat that as mandatory, not optional. Accessibility usually takes effect immediately for a process that’s already running; relaunch it only as a fallback if it still isn’t detected.

Verifying it actually took

The most reliable check is the doctor, covered in full on the next page:


"/Applications/autonomy (a7y).app/Contents/Resources/bin/a7y-cli" doctor

Look for macos-accessibility and macos-screen-recording (or the equivalent) under the macOS Permissions phase. You can also use the app’s own Run Doctor command (in the toolbar or command palette) to see the same output in a “Doctor Results” window without opening a terminal at all.

There’s a real, easy-to-miss distinction here. a7y-cli doctor’s Accessibility/Screen Recording checks test the permission of whatever process is running the CLI (your terminal, most likely) — they probe with osascript/screencapture, not by asking the app bundle about its own grant. That’s a different grant than the one the app bundle itself needs and requests through its setup wizard. If doctor reports Accessibility as missing from a terminal that has never been added to System Settings, that failure is about the terminal, not about whether the app itself is authorized. When in doubt, use the app’s own Run Doctor command or its permissions output instead of a bare terminal invocation, and add your terminal to both panes too if you plan to drive a7y-cli from it directly.

Optional permissions

Depending on the workflow you choose in the setup wizard, Autonomy may also probe for microphone, speech recognition, and Personal Voice access — these support voice input and Personal Voice output, and are requested only when relevant, not as a blanket ask.

Pitfalls

Restart your terminal, not just the app, if you’re driving a7y-cli from a shell. A shell session opened before you granted its permission won’t see the update until it’s restarted.
Permissions survive reinstalls, but only if the app’s identity doesn’t change. See Install for why plugins/autonomy/scripts/install-app.sh refuses identity-changing replacements by default — that refusal is what protects the grants you just made here.
A denied Screen Recording grant doesn’t block everything. AX-only review (forms, labels, document structure) keeps working; only visual verification and vision-fallback paths degrade.

If either permission won’t stick, see Permissions missing or not taking effect. Otherwise, continue to Run the doctor.