Question 1

What macOS versions are supported by Avelyn?

Accepted Answer

Avelyn supports macOS Sonoma (14.0+) and macOS Sequoia (15.0+). Both Apple Silicon (M1/M2/M3/M4) and Intel Macs are natively supported.

Question 2

How do I install Avelyn on my Mac?

Accepted Answer

Download the `.dmg` installer from our website, open the disk image, and drag Avelyn into your Applications folder. On first launch, the onboarding wizard guides you through granting Accessibility permissions.

Question 3

Why does Avelyn require macOS Accessibility permissions?

Accepted Answer

Accessibility permissions allow Avelyn to read the currently highlighted text in any app (Chrome, Xcode, Slack, Pages, Notes) and paste the AI-enhanced text seamlessly back into your active cursor location.

Question 4

Why does Avelyn ask for Input Monitoring permissions?

Accepted Answer

Input Monitoring allows Avelyn to listen for your global system-wide hotkey trigger (Option+Space or custom shortcut) even when Avelyn is running in the background menu bar.

Question 5

Can I install Avelyn via Homebrew?

Accepted Answer

Yes! You can install Avelyn via Homebrew Cask using `brew install --cask avelyn`.

Question 6

Does Avelyn auto-update itself?

Accepted Answer

Avelyn includes a non-intrusive update checker that notifies you in the system tray when a new stable release is available.

Question 7

How do I trigger the auto-installer overlay during first setup?

Accepted Answer

If you do not have Ollama installed, Avelyn automatically detects it on startup and displays an overlay wizard that downloads Ollama and pulls recommended default models like Gemma 3.

Question 8

What should I do if macOS says 'Avelyn cannot be opened because it is from an unidentified developer'?

Accepted Answer

Avelyn is signed and notarized by Apple. If you encounter Gatekeeper warnings, open System Settings → Privacy & Security, scroll to Security, and click 'Open Anyway'.

Question 9

Can I run Avelyn without administrator rights?

Accepted Answer

Yes, Avelyn runs in user space inside your `~/Applications` folder. Admin rights are only needed once to grant initial Accessibility permissions in macOS Settings.

Question 10

How do I verify the integrity of the downloaded DMG package?

Accepted Answer

We publish SHA-256 checksums for every release on our GitHub Releases page. You can verify your download using `shasum -a 256 Avelyn-Installer.dmg`.

Question 11

Does Avelyn run on Windows or Linux?

Accepted Answer

Avelyn's core architecture is built with cross-platform Python and PyQt6. The macOS version is fully released, while Windows and Linux builds are in active preview.

Question 12

How do I completely uninstall Avelyn?

Accepted Answer

To completely uninstall, drag Avelyn from Applications to Trash, and delete the user config folder at `~/.avelyn`.

Question 13

Does Avelyn support silent deployment for enterprise fleets?

Accepted Answer

Yes, system administrators can deploy Avelyn via MDM profiles (Jamf, Kandji) pre-granting TCC permissions and distributing standard `config.json` templates.

Question 14

Can I customize the installation directory?

Accepted Answer

Avelyn can be placed in `/Applications` for all users or `~/Applications` for single-user installations.

Question 15

What happens if I update macOS from Sonoma to Sequoia?

Accepted Answer

macOS updates may occasionally reset TCC permissions. If Avelyn stops capturing text after a major OS upgrade, simply toggle Accessibility off and on in System Settings.

Question 16

What is Prompt Enhancement?

Accepted Answer

Prompt Enhancement takes brief or raw user instructions (e.g., 'fix email') and expands them into structured, context-rich prompts before sending them to the AI provider.

Question 17

How does Grammar Correction work in Avelyn?

Accepted Answer

Grammar Correction fixes spelling mistakes, punctuation errors, awkward phrasing, and verb tense inconsistencies without altering your original tone or meaning.

Question 18

What does the Professional Writing mode do?

Accepted Answer

Professional mode elevates casual writing into clear, authoritative executive communication suitable for reports, memos, and client emails.

Question 19

How does Email Writing mode work?

Accepted Answer

Email mode reformats raw bullet points into polished business emails complete with subject lines, greeting structures, and call-to-action closings.

Question 20

What options are available in AI Rewrite mode?

Accepted Answer

AI Rewrite supports tone shifting (formal, persuasive, concise, friendly), text expansion, text shortening, and style adaptation.

Question 21

How many languages are supported in Translation mode?

Accepted Answer

Avelyn supports instant translation across 50+ major languages including Spanish, French, German, Japanese, Chinese, Portuguese, Hindi, and Arabic.

Question 22

What does Summarization mode do?

Accepted Answer

Summarization extracts key takeaways, executive summaries, or bulleted action items from long articles, PDFs, and meeting notes.

Question 23

How does the Coding Assistant mode help developers?

Accepted Answer

Coding Assistant refactors messy code, adds docstrings, explains complex functions, generates unit tests, and fixes syntax bugs inside VS Code, Xcode, or JetBrains IDEs.

Question 24

Can I create custom modes in Avelyn?

Accepted Answer

Yes! You can add custom mode presets in Settings with custom system prompts tailored to your specific workflow or industry.

Question 25

What is the Command Palette?

Accepted Answer

The Command Palette is a floating overlay triggered by your hotkey. It displays preset action buttons, custom prompt text inputs, and streaming AI response previews.

Question 26

How does Instant Text Replacement work?

Accepted Answer

After the AI generates the output, Avelyn copies the output to the clipboard and sends a synthetic `Cmd+V` event to paste it right back over your selected text.

Question 27

Can I cancel a streaming AI generation mid-way?

Accepted Answer

Yes! Pressing `Escape` or clicking the cancel button instantly stops the active HTTP stream without modifying your text.

Question 28

Does Avelyn preserve original clipboard history?

Accepted Answer

Yes! Avelyn saves your existing clipboard contents prior to processing and restores your original clipboard item shortly after performing the text replacement.

Question 29

What is Push-to-Talk (PTT) Voice Control?

Accepted Answer

Push-to-Talk allows you to hold down a hotkey, speak your instruction into your Mac's microphone, and let Avelyn execute the command hands-free.

Question 30

How does Tone Shifting work?

Accepted Answer

Tone Shifting alters emotional register—transforming blunt draft notes into warm customer support replies or firm contract follow-ups.