Permissions
What capture needs on each operating system, without euphemism.
Capture works by registering a global shortcut, copying the current selection, reading the clipboard, restoring the previous clipboard, and asking the OS for the frontmost app and window title.
That is a documented, realistic mechanism. It is also imperfect. Snibl never fails this path silently: a failed shortcut registration shows a banner and a Settings status, and a capture that copies nothing (the sentinel is still on the clipboard) shows a subtle notification.
Shortcut
The default is Ctrl+Option+G on macOS and Ctrl+Alt+G on Windows and Linux (Control+Alt+G). It is chosen because it is not a common Chrome, Safari, or Finder shortcut. Record a replacement in Settings → Capture: click the shortcut field, press the keys, and Snibl shows them live as key caps. Esc cancels. Backspace clears. Reset to default restores Ctrl+Option+G / Ctrl+Alt+G.
Capture shortcuts need at least three keys: two or more modifiers plus one non-modifier key (for example ⌘⇧M or Ctrl+Alt+G). The recorder does not save a shorter combo; it shows a quiet hint, Use two modifiers plus a key. Older double-tap shortcuts (DoubleTap+…) and one-modifier combos are replaced on load with the last working three-key shortcut, or Control+Alt+G.
Cmd+Shift+G / Ctrl+Shift+G clashes with:
- Chrome and Safari find previous
- Finder Go to Folder
If the shortcut cannot be registered, or it clashes, Settings shows an inline error, Not registered when registration failed, a dismissible banner appears, and the main process logs [snibl:capture] shortcut_register_failed. Use the tray item Capture selection as a fallback. The banner can be dismissed; it stays dismissed across launches until the shortcut registers. Settings → Permissions remains the place to fix it.
Combos use Electron globalShortcut.
macOS Accessibility
Capture on macOS needs Accessibility. Grant it here:
- Open System Settings.
- Go to Privacy & Security.
- Open Accessibility.
- Enable the process that is actually running Snibl.
In development (pnpm dev:desktop / electron-vite), macOS attributes that permission to Electron or to the terminal you ran pnpm dev:desktop from (Terminal, iTerm, Cursor), not to “Snibl”. Enable Electron, and if you started from a terminal, enable that terminal too. After a packaged install, enable Snibl.
The Settings button calls systemPreferences.isTrustedAccessibilityClient(true) and opens System Settings → Privacy & Security → Accessibility. Snibl reads the state with isTrustedAccessibilityClient(false).
Accessibility is required to send ⌘C to the frontmost app and to read the frontmost process name and window title. Snibl polls CGEventSourceFlagsState in this process (via CoreGraphics, with a JXA fallback) until Control/Option/Shift/Command are released, then posts a keyboard event whose flags are only Command (CGEventSetFlags). System Events keystroke "c" using command down is the fallback; that path ORs currently held modifiers, which is why the wait still matters. Snibl then writes a clipboard sentinel and polls for up to 1s (retrying copy once) instead of sleeping a fixed delay.
- Automation may also prompt so the same process can control System Events. Allow it.
- Apple Events are used to read the front tab URL from Safari and Chromium-based browsers (Chrome, Chrome Canary, Chromium, Brave, Edge, Arc, Dia, Vivaldi, Opera) when the frontmost app is one of those. macOS may show an Automation prompt the first time Snibl talks to that browser. Snibl does not wait on that lookup: capture saves the text first, and the URL is attached later if AppleScript returns one. Browsers can refuse. Unsigned local builds may prompt or fail. If Automation is denied, capture still succeeds without a URL.
- Notifications use Electron
Notificationwithsilent: true. macOS only delivers them for signed apps. Unsigned dev builds may emitfailed. Empty captures still attempt the same notification with the bodyNothing captured: no text selected or permission missing.
Windows
- Copy waits until Shift/Ctrl/Alt/Win are released (same cap as macOS, via
GetAsyncKeyState), then sendsSendKeys^c. No Accessibility grant is required. Elevated windows can ignore the keystroke. - The foreground window title is read with
GetForegroundWindow/GetWindowText. - Browser URLs are not read from Chrome/Edge address bars. If the window title itself contains an
http(s)URL, Snibl stores that. Otherwise the detail view shows the window title.
Linux
- On X11, capture uses
xdotoolforCtrl+Cand the active window title. Installxdotool. - On Wayland, global shortcuts go through the desktop portal (
org.freedesktop.portal.GlobalShortcuts). Synthetic keystrokes are often blocked. Capture from other apps is unreliable. - Browser URLs are not read from the browser. If the window title contains an
http(s)URL, Snibl stores that. - Set
desktopName/StartupWMClasstosniblso the portal can bind shortcuts.
Debug log (main process)
Each capture attempt prints structured lines prefixed with [snibl:capture]:
shortcut_register/shortcut_register_failedshortcut_fired(trigger:shortcut,tray,ipc, orsmoke)permission_statemodifiers_releasedsentinel_setclipboard_poll(one line per attempt;copy_retryif the first copy left the sentinel)clipboard_restoredcopy_attemptedclipboard_changeditem_savedwithid, orcapture_failedwithreasonclassification_resultsource_url_attachedwhen a browser URL arrives after save
What Snibl will not do
Snibl does not inject into other processes, scrape every window, or keep a keylogger. Capture only reads the selection at the moment you press the shortcut, by asking the frontmost app to copy.