Troubleshooting

Autonomy’s troubleshooting surface is small on purpose: almost every problem traces back to one command, a7y-cli doctor, and one shared mechanism, the serialized VoiceOver speech queue. Start there before chasing anything else.

Start With The Doctor

a7y-cli doctor

Doctor runs four gated phases, in order. If a phase fails, the phases after it are skipped — they cannot succeed without the earlier one, so fixing issues out of order wastes time:

1. Prerequisites — toolchain, a7y/a7y-cli binaries, browser, extension.
2. macOS Permissions — Accessibility and Screen Recording.
3. Daemon & Relay — is the daemon running, is the relay port healthy.
4. Browser Lane — debug port, Chrome for Testing.

Each failing check prints its own fix — a concrete next step, not a generic error. Run with --verbose for extra environment detail, including daemon attachment state and a participant-readiness report:

a7y-cli doctor --verbose

For a fuller pass that also checks live session readiness (relay, extension, sessions), run:

a7y-cli validate --verbose

The Accessible, Voice-First Path

Many Autonomy users are running screen-off, by voice, and cannot read a terminal. Doctor’s checks and fixes are designed to survive being spoken aloud or relayed by an agent, but an agent itself can also read the same permission state directly — no shell required — by calling the accessibility_state or doctor_check_permissions MCP tools, or by running:

a7y-cli tools accessibility-state --prompt

This works even when the daemon isn’t running yet, so it’s the right first probe for an agent to run on a user’s behalf before assuming anything is broken. Never report a permission or delivery problem as fixed just because a tool call returned success — spoken delivery in particular is evidence of an attempt, not proof the user heard it. See Spoken Updates Are Not Heard for what the delivery evidence actually promises.

Common Problems

• Accessibility or Screen Recording permission missing
• MCP tools not visible in the agent
• Spoken updates are not heard
• Two agents talk over each other
• The daemon closes a request

Before Asking For Help

Collect a diagnostics bundle rather than pasting logs by hand:

scripts/collect-diagnostics.sh

This tarballs the doctor output, daemon state, and logs. Share it when reporting an issue. See also Run the doctor and Grant permissions for the setup steps these fixes assume you’ve already been through once.