From 6b954896726e765fc9e4ceae2ec663386b2f5641 Mon Sep 17 00:00:00 2001 From: sttlab-tech Date: Mon, 10 Aug 2026 12:18:17 +0200 Subject: [PATCH] Add README with install and Gatekeeper bypass instructions --- README.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..d897631 --- /dev/null +++ b/README.md @@ -0,0 +1,74 @@ +# FocusFixer + +Native macOS menu-bar utility that fixes a long-standing multi-display bug: after clicking a +window on one screen, keyboard focus can stay on a window on another screen, so typing goes to +the wrong place. Download, unzip, run — grant Accessibility when prompted (see `CLAUDE.md` for +how the app is built). + +## Installing from a downloaded release + +Grab `FocusFixer-vX.Y.Z.zip` from the +[releases page](https://gitea.sttlab.eu/stt/focus-fixer/releases), unzip it, and drag +`FocusFixer.app` to `/Applications`. + +The app is signed with a self-signed identity (`sttlab-apps`), not an Apple Developer ID — +there's no paid Apple account behind this project. macOS's Gatekeeper doesn't trust that +signature by default, so on first launch of a version downloaded from a browser (which +macOS marks with a quarantine flag) you'll likely see it refuse to open, or ask to move it to +the bin. Pick **one** of the two options below to get past that — you don't need both. + +### Option 1 — Trust the `sttlab-apps` certificate + +This tells your Mac to trust anything signed by this specific certificate going forward, so +you won't need to repeat this for future versions of the app (as long as it keeps being signed +with the same identity). + +1. Get the certificate: `sttlab-apps.cer` (ask for it, or export it yourself if you have + access to the machine it was created on: `security find-certificate -c "sttlab-apps" -p + > sttlab-apps.cer`). +2. Import it into your login keychain: + ```bash + security import sttlab-apps.cer -k ~/Library/Keychains/login.keychain-db + ``` +3. Trust it, but **only** for code signing (not as a general root CA): + ```bash + security add-trusted-cert -r trustRoot -p codeSign \ + -k ~/Library/Keychains/login.keychain-db sttlab-apps.cer + ``` + macOS will prompt for your login password — that's it asking permission to change + keychain trust settings, not this command asking for a password directly. +4. Open `FocusFixer.app` normally (double-click, or `open /Applications/FocusFixer.app`). + +### Option 2 — Bypass Gatekeeper for this app only + +No trust changes, no certificate needed — just tells macOS to stop flagging this specific +app. You'll need to repeat this for each new version you download (the quarantine flag is +set per downloaded file). + +Either: + +- Right-click `FocusFixer.app` in Finder → **Open** → **Open** again in the confirmation + dialog. (Regular double-click won't offer this the first time; right-click → Open does.) + +Or, from a terminal: + +```bash +xattr -dr com.apple.quarantine /Applications/FocusFixer.app +``` + +(`-r` because it's a bundle — the quarantine flag can be set on files inside it too, not just +the top-level `.app`.) + +Both achieve the same result: the app opens. Option 1 is the better choice if you expect to +download future versions and don't want to repeat the bypass each time; Option 2 is faster +for a one-off. + +## Granting Accessibility permission + +FocusFixer needs Accessibility access to watch clicks and reassert focus — it can't do +anything useful without it. On first launch it prompts for the grant automatically; if you +miss the prompt or need to re-grant it later, go to **System Settings → Privacy & Security → +Accessibility** and enable FocusFixer there. + +FocusFixer has no Dock icon and no regular window — look for its icon in the menu bar. That +menu is also where you toggle it on/off and enable/disable launching at login.