Install

Autonomy’s runtime ships as a7y-mcp and a7y-cli — plain binaries — but on macOS they run inside a small app bundle, autonomy (a7y).app. That bundle isn’t cosmetic: it’s the thing macOS attaches your Accessibility and Screen Recording grants to. Install it once, correctly, and every later step in Getting started — permissions, the doctor, connecting an agent — has something stable to point at.

This page is the one genuinely developer-facing step in the whole path. Once the app is installed, granting permissions, running the doctor, and connecting an agent can all be talked through by voice if you’re setting this up for (or as) a screen-off user. Getting the bits onto the machine in the first place still takes a terminal.

There is no signed download for this yet. The build below uses a locally generated, stable development signing identity — not an Apple Developer ID — created the first time you run it. That’s enough for Accessibility/Screen Recording grants to survive rebuilds on your machine; it is not a notarized release. The source repository is also not public yet, so this assumes you’re starting from a local checkout, not a git clone URL.

Why the app bundle, specifically

macOS ties Accessibility and Screen Recording grants to two things: an app’s bundle identifier and its designated code requirement (roughly: “this exact signing identity produced this binary”). Change either one — by rebuilding with a different signing identity, for instance — and macOS quietly treats the new build as a different app, so it asks the user to grant both permissions again. For a screen-off user, an unexpected re-grant prompt is not a minor inconvenience; it can be a wall.

Autonomy’s install script exists specifically to prevent that: it creates one stable local signing identity the first time, reuses it on every later build, and refuses to install a rebuild that would change the app’s permission identity unless you explicitly override it.

Build and install

Update your checkout

From your local checkout of the repo, on the beta branch:


git switch beta
git pull --rebase

Run the installer


plugins/autonomy/scripts/install-app.sh

With no flags, this single command:

builds the Rust workspace and the browser extension, and code-signs the app with a stable local development identity (creating one on first run);
installs the bundle to /Applications/autonomy (a7y).app — refusing the install if it would change the bundle identifier or code requirement of an already-installed copy;
starts the app-owned daemon;
runs the app’s own self-tests and plugins/autonomy/scripts/doctor.sh;
opens the app.

A clean run ends with the app open and a passing autonomy (a7y) plugin doctor passed. line. If you only want to rebuild without reinstalling opening the app, or want to skip parts of the build for a faster iteration loop, run plugins/autonomy/scripts/install-app.sh --help for the flags (--no-build, --skip-cargo, --skip-extension, --no-open, --no-doctor).

The one flag you should treat as a deliberate choice

If a rebuild really did need to change the app’s signing identity — for example, you’re intentionally switching from ad-hoc to the stable dev identity — the installer stops and tells you so instead of silently replacing the app:


Refusing to replace autonomy (a7y): bundle identifier would change
...
If you intentionally want the one-time permission reset, rerun with:
  plugins/autonomy/scripts/install-app.sh --allow-identity-change

Only pass --allow-identity-change when you mean it — it’s the difference between “the app updated” and “the user has to grant Accessibility and Screen Recording all over again.”

Pitfalls

Two install scripts exist; they do different things. The root README’s Quick Start also mentions plugins/autonomy/scripts/install.sh, which builds the app and copies the plugin into ~/.agents/plugins/... for Codex’s personal plugin marketplace — it does not install anything to /Applications. Autonomy’s Claude Code and Codex plugins both ship an .mcp.json that points at /Applications/autonomy (a7y).app, so install-app.sh (this page) is the script that actually leaves you in a state where an MCP-connected agent can find the app. If you’ve run install.sh instead and an agent can’t see any tools later, this is why — see MCP tools not visible.
Don’t hand-copy the app bundle. Moving or duplicating autonomy (a7y).app outside of install-app.sh risks breaking the exact code requirement macOS checks, which throws away your permission grants for no reason. Always reinstall through the script.
Building requires Xcode’s Swift toolchain and a Rust 1.85+ / edition 2024 toolchain locally; a7y-cli doctor (see Run the doctor) will tell you plainly if either is missing, and skips the Rust requirement entirely if prebuilt a7y/a7y-cli binaries are already present.

Next: Grant permissions.