| 1 |
# Accessibility Permissions |
| 2 |
|
| 3 |
tarmac relies on the macOS Accessibility API (AXUIElement) to inspect and manipulate windows. Without this permission, tarmac cannot: |
| 4 |
|
| 5 |
- Read window positions and sizes |
| 6 |
- Move or resize windows |
| 7 |
- Detect window focus changes |
| 8 |
- Query minimum window sizes |
| 9 |
|
| 10 |
## How tarmac checks permissions |
| 11 |
|
| 12 |
At startup, tarmac calls `AXIsProcessTrustedWithOptions` to check whether it has Accessibility access. If the check fails, it logs a warning and continues running — but it won't be able to manage windows. |
| 13 |
|
| 14 |
The check happens once at launch. If you grant permissions while tarmac is already running, you'll need to restart it. |
| 15 |
|
| 16 |
## Granting access |
| 17 |
|
| 18 |
### macOS Ventura and later (System Settings) |
| 19 |
|
| 20 |
1. Open **System Settings** |
| 21 |
2. Go to **Privacy & Security → Accessibility** |
| 22 |
3. Click the lock and authenticate |
| 23 |
4. Click **+** — a Finder dialog opens |
| 24 |
5. Press **Cmd+Shift+G** to open the "Go to Folder" field. Finder doesn't show `/usr/local` or `/opt/homebrew` by default — this shortcut lets you type a path directly. |
| 25 |
6. Type the path to the tarmac binary: |
| 26 |
- Homebrew: `/opt/homebrew/bin/tarmac` |
| 27 |
- Manual install: `/usr/local/bin/tarmac` |
| 28 |
7. Select `tarmac` and click Open |
| 29 |
8. Make sure the toggle is **on** |
| 30 |
|
| 31 |
### macOS Monterey (System Preferences) |
| 32 |
|
| 33 |
1. Open **System Preferences → Security & Privacy → Privacy** |
| 34 |
2. Select **Accessibility** in the sidebar |
| 35 |
3. Click the lock and authenticate |
| 36 |
4. Click **+** and add the tarmac binary |
| 37 |
|
| 38 |
<img |
| 39 |
src="/accessibility-permissions.png" |
| 40 |
alt="macOS System Settings — Privacy & Security — Accessibility panel with tarmac enabled" |
| 41 |
width={800} |
| 42 |
height={600} |
| 43 |
className="rounded-lg border border-surface-200 dark:border-surface-700 my-6" |
| 44 |
loading="lazy" |
| 45 |
/> |
| 46 |
|
| 47 |
## Permission revoked after rebuild |
| 48 |
|
| 49 |
macOS ties Accessibility permission to the binary's code signature. If you rebuild tarmac from source, the new binary has a different ad-hoc signature, and macOS silently revokes the permission. |
| 50 |
|
| 51 |
Symptoms: |
| 52 |
- tarmac starts but doesn't tile anything |
| 53 |
- Log shows `AXIsProcessTrusted: false` |
| 54 |
|
| 55 |
Fix: remove the old entry from Accessibility settings and re-add the new binary. |
| 56 |
|
| 57 |
If you're rebuilding frequently during development, you can use `tccutil` to reset the permission database (requires admin): |
| 58 |
|
| 59 |
```bash |
| 60 |
sudo tccutil reset Accessibility com.gardesk.tarmac |
| 61 |
``` |
| 62 |
|
| 63 |
Then re-grant access through System Settings. |
| 64 |
|
| 65 |
## ers also needs Accessibility |
| 66 |
|
| 67 |
If you're using [ers](/docs/ers/overview) for window borders, it also needs Accessibility permissions. Add the `ers` binary to the same Accessibility list. ers needs it to detect focus changes and query window geometry. |
| 68 |
|
| 69 |
## Troubleshooting |
| 70 |
|
| 71 |
### "tarmac is not in the Accessibility list" |
| 72 |
|
| 73 |
If you installed via Homebrew, the binary may be at a different path (e.g., `/opt/homebrew/bin/tarmac`). Add that path instead. |
| 74 |
|
| 75 |
### "Permission granted but windows still don't tile" |
| 76 |
|
| 77 |
1. Restart tarmac after granting permission |
| 78 |
2. Check that the correct binary is listed (not an older version) |
| 79 |
3. Run `RUST_LOG=tarmac=debug tarmac` and look for AX-related errors in the output |
| 80 |
|