Accessibility Permissions

tarmac relies on the macOS Accessibility API (AXUIElement) to inspect and manipulate windows. Without this permission, tarmac cannot:

  • Read window positions and sizes
  • Move or resize windows
  • Detect window focus changes
  • Query minimum window sizes

How tarmac checks permissions

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.

The check happens once at launch. If you grant permissions while tarmac is already running, you'll need to restart it.

Granting access

macOS Ventura and later (System Settings)

  1. Open System Settings
  2. Go to Privacy & Security → Accessibility
  3. Click the lock and authenticate
  4. Click + — a Finder dialog opens
  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.
  6. Type the path to the tarmac binary:
    • Homebrew: /opt/homebrew/bin/tarmac
    • Manual install: /usr/local/bin/tarmac
  7. Select tarmac and click Open
  8. Make sure the toggle is on

macOS Monterey (System Preferences)

  1. Open System Preferences → Security & Privacy → Privacy
  2. Select Accessibility in the sidebar
  3. Click the lock and authenticate
  4. Click + and add the tarmac binary
macOS System Settings — Privacy & Security — Accessibility panel with tarmac enabled

Permission revoked after rebuild

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.

Symptoms:

  • tarmac starts but doesn't tile anything
  • Log shows AXIsProcessTrusted: false

Fix: remove the old entry from Accessibility settings and re-add the new binary.

If you're rebuilding frequently during development, you can use tccutil to reset the permission database (requires admin):

sudo tccutil reset Accessibility com.gardesk.tarmac

Then re-grant access through System Settings.

ers also needs Accessibility

If you're using ers 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.

Troubleshooting

"tarmac is not in the Accessibility list"

If you installed via Homebrew, the binary may be at a different path (e.g., /opt/homebrew/bin/tarmac). Add that path instead.

"Permission granted but windows still don't tile"

  1. Restart tarmac after granting permission
  2. Check that the correct binary is listed (not an older version)
  3. Run RUST_LOG=tarmac=debug tarmac and look for AX-related errors in the output