Run the doctor

a7y-cli doctor is Autonomy’s readiness check: one command that tells you, in order, exactly what’s missing before an agent can do anything useful on your Mac. It exists so that a broken environment produces one clear, ordered fix list instead of a cascade of confusing downstream errors — a missing Accessibility grant, left unchecked, would otherwise surface later as an opaque daemon or MCP failure with no obvious cause.

Run it after installing the app and granting permissions, and again any time something that used to work stops working.

Run it

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

Add --verbose for extra detail — daemon attachment info and a participant readiness report (memory/events DB paths, access-config profile, required vs. risky tool groups):

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

If you’d rather not open a terminal, use the app’s own Run Doctor command (available from the toolbar and the command palette) — it runs the identical check and shows the output in a “Doctor Results” window, with an accessible label a screen reader will announce.

How it’s organized

Doctor runs four phases, in order, and each phase gates the next — if anything in a phase fails, later phases are skipped rather than run against a foundation that isn’t ready yet:

 Phase 1  Prerequisites     toolchain, a7y/a7y-cli binaries, browser extension
    |
    v  (must pass)
 Phase 2  macOS Permissions   Accessibility, Screen Recording
    |
    v  (must pass)
 Phase 3  Daemon & Relay      daemon running, relay port healthy
    |
    v  (must pass)
 Phase 4  Browser Lane        debug port, Chrome for Testing (browser workflows only)

This is why doctor is worth running rather than skipping to Connect your first agent directly: a failure two phases back can look like an MCP connection problem when it isn’t one.

Reading the output

Each check prints a pass (✓) or fail (✗) line with a short detail. When everything passes:

All 15 checks passed. Environment is ready.

Next steps to reach a working session:
  1. a7y-cli daemon start
  2. ...

(Ignore the daemon-start suggestion in that summary if you installed via install-app.sh — the app already starts and owns its own daemon; you don’t need a second one for the connect an agent step.)

When something fails, doctor tells you which checks, in which phase, and gives a specific remediation for each — including exact System Settings panes to open and exact commands to run:

2 passed, 1 failed.

Fix these issues in order:

  1. macos-accessibility (Phase 2)
     1. Open System Settings > Privacy & Security > Accessibility.
     2. Enable the toggle for Autonomy (or your terminal app, if you're
        running the CLI directly) — modern macOS lists it automatically;
        there is no "+" button to click.
     3. Quit and reopen the app (or restart your terminal session) after
        enabling; the grant only takes effect on relaunch.

Later-phase checks were skipped — they run once the above is fixed.

Fix the first failure, rerun doctor, and repeat — don’t try to fix everything at once from a single run’s output, since later-phase failures may resolve themselves once the earlier ones are fixed.

Pitfall: doctor checks the calling process, not the app bundle

This is worth repeating from Grant permissions: a7y-cli doctor’s Accessibility and Screen Recording checks test whichever process invoked the CLI (your terminal), by probing with osascript and screencapture. That is a separate grant from the app bundle’s own Accessibility/Screen Recording authorization, which the setup wizard requests directly. Both matter, but for different things: the terminal’s grant matters if you’re calling a7y-cli directly from a shell; the app bundle’s grant is what an MCP-connected agent actually depends on. Don’t assume a green doctor run from your terminal proves the app itself is authorized, or vice versa — check both if either one surprises you.

Pitfall: a stale daemon can eat two ports

Doctor’s Daemon & Relay phase checks that the relay port (4201) is either free or already held by a healthy Autonomy daemon. If you see port 4201 in use and doctor’s daemon check still fails, something other than Autonomy’s own daemon may be squatting on it — quit any stray autonomy-a7y processes and rerun doctor before assuming the install is broken. If the daemon keeps closing requests even after that, see The daemon closed a request.

Once doctor passes cleanly, continue to Connect your first agent.