Troubleshooting

1. Ruru cannot detect active caret or insert text

If Ruru triggers but fails to read the surrounding text or insert the response back into your app, the macOS Accessibility database may have become stale after an OS update:

• Open System Settings > Privacy & Security > Accessibility.
• Toggle Ruru off, wait a few seconds, and toggle it back on.
• If the issue persists, reset Accessibility permissions for Ruru via Terminal:

tccutil reset Accessibility com.atcharm.ruru

2. Global hotkeys (⌥Space or @@) do not respond

Summon gestures require Input Monitoring permission. If shortcuts stop working:

tccutil reset ListenEvent com.atcharm.ruru

Then relaunch Ruru and re-enable permission when prompted.

3. Blank OCR text from screen captures

Ensure Screen Recording permission is enabled under System Settings > Privacy & Security > Screen Recording.

'Command not found' for CLI agents

Ruru runs CLI agents through your interactive login shell. If a tool installed via Homebrew, pnpm, or pyenv is not found:

• Check where the tool is installed by running which claude or which agy in your terminal.
• In Ruru Settings > Agents, enter the absolute path (e.g. /opt/homebrew/bin/claude) in the Binary field.
• Ensure your PATH export is defined in ~/.zshrc rather than only in non-login config files.

Lost license key

License keys are delivered by our Merchant of Record, Polar. If you cannot locate your email receipt, log in to the Polar customer portal using the email address used during purchase to retrieve your key.

Offline usage

Ruru stores a local unsigned license cache for up to 30 days of offline travel. Connect to the internet once every 30 days to allow Ruru to refresh its validation record.