macOS Permissions Setup Guide
Granting Accessibility and Input Monitoring permissions to enable global text replacement.
Why Avelyn Needs macOS Permissions
Avelyn is a privacy-first system-wide application. To refine highlighted text inside external applications (Chrome, Xcode, Slack, Apple Notes, Mail) without requiring individual browser extensions or IDE plugins, macOS requires explicit security authorization under Transparency, Consent, and Control (TCC).
1. Accessibility Permission
Purpose: Allows Avelyn to read the highlighted text in the currently active window and execute synthetic Cmd+V paste events to replace original text seamlessly.
How to Enable Accessibility:
- Open System Settings on your Mac.
- Navigate to Privacy & Security → Accessibility.
- Click the + (Plus) button or toggle the switch next to Avelyn to
ON. - If prompted, enter your Mac administrator password.
2. Input Monitoring Permission
Purpose: Allows Avelyn to listen for your global trigger shortcut (e.g., Option+Space) while running in the background menu bar tray.
How to Enable Input Monitoring:
- Open System Settings.
- Navigate to Privacy & Security → Input Monitoring.
- Ensure the toggle switch next to Avelyn is set to
ON.
Troubleshooting Revoked Permissions
If Avelyn stops replacing text after updating macOS, Apple security policies may have invalidated the old app signature hash.
To fix: Open System Settings → Accessibility, select Avelyn, click the - (Minus) button to remove the old entry, then re-add Avelyn from your /Applications folder.