AutoAllowScreenCapture.spoon

A Hammerspoon Spoon that automatically approves macOS's screen/audio capture picker alert for a configurable list of trusted applications — no more clicking "Allow" every time a trusted app asks to record your screen.

🎯 Purpose

When an app uses macOS's private window-picker API to request screen or audio capture, the system shows a dialog like:

"AppName" is requesting to bypass the system private window picker and directly access your screen and audio.

AutoAllowScreenCapture watches for that specific system dialog and, if it matches one of your trusted apps, presses Allow for you automatically.

It only acts on a genuine OS-presented dialog — it checks the window's accessibility role (AXWindow), subrole (AXSystemDialog), and owning bundle ID (com.apple.UserNotificationCenter), then confirms the exact label text against your configured app names, before pressing anything. So, if you have not added the name of the application into the preferences file or the dialog belongs to some other application, then the request legitimately requires your attention.

✅ Requirements

• Hammerspoon installed and running
• Hammerspoon granted Accessibility permission (System Settings → Privacy & Security → Accessibility)

📦 Installation

git clone https://github.com/mdarrint/AutoAllowScreenCapture.spoon ~/.hammerspoon/Spoons/

Important

Before reloading, create the preferences directory and config file (~/.hammerspoon/Prefs/auto-allow-apps.json) — without it, the watcher won't install. See Configuration below for details.

Then add to ~/.hammerspoon/init.lua:

hs.loadSpoon("AutoAllowScreenCapture")
spoon.AutoAllowScreenCapture:start()

Reload your Hammerspoon config.

⚙️ Configuration

For security purposes, the preferences are kept outside of the spoon directory. So, create the preferences directory and config file outside this Spoon, in your Hammerspoon config directory:

mkdir -p ~/.hammerspoon/Prefs && echo '{"appnames":[],"loglevel":"info"}' > \
 ~/.hammerspoon/Prefs/auto-allow-apps.json

Then edit appnames to list your trusted apps using the name of the apps that you see in the dialog when it appears e.g.:

{
  "appnames": ["Thaw", "RustDesk"],
  "loglevel": "info"
}

Field	Type	Notes
appnames	array of strings	App names exactly as they appear in the system dialog. May be empty — the watcher just won't install.
loglevel	string or number	One of nothing, error, warning, info, debug, verbose, or the corresponding number 0–5 (per hs.logger). Defaults to "info" if the file is missing.

Changes don't apply live. After editing the config file, call:

spoon.AutoAllowScreenCapture:reloadApps()

or reload Hammerspoon entirely (hs.reload()).

Validation behavior

The config is validated on every load. Any of the following leaves the Spoon inert (no watcher installed) and logs a specific error:

• Missing or empty config file → warning, watcher disabled (not a hard failure)
• Malformed JSON
• appnames missing or not an array
• loglevel present but not one of the recognized values

🐛 Debugging

Logs go through hs.logger under the name AutoAllowSC:

spoon.AutoAllowScreenCapture.logger.setLogLevel("debug")

Two test helpers let you check the matching logic without waiting for a real dialog:

-- Test the label-matching logic against a plain string
spoon.AutoAllowScreenCapture:testLabelMatch('"Thaw" is requesting to bypass the system private window picker and directly access your screen and audio.')

-- Test the full gate (role/subrole/bundle ID + label) against a captured window object
spoon.AutoAllowScreenCapture:testWindow(win)

📚 API Reference

Method	Description
:init()	Called automatically by hs.loadSpoon(). Loads and validates config.
:start()	Installs the window watcher. No-op if no apps are configured.
:stop()	Removes the window watcher.
:reloadApps()	Re-reads and re-validates the config file, then restarts the watcher. Required after any config change.
:testLabelMatch(value)	Tests a plain string against the configured label patterns. Returns the matched app name or nil.
:testWindow(win)	Runs the full match gate against a real window object. Returns the matched app name or nil.
:configPath()	Returns the full path to the expected config file.

Property	Description
.apps	Array of currently loaded, trusted app names.
.logger	The hs.logger instance (AutoAllowSC).
.name, .version, .author, .license	Standard Spoon metadata.

📝 Release Notes

v1.1.0

• Fixed a window-handling race condition in LuaSkin: the window is now moved off screen first, letting other processes update, before it's auto-closed.
• Updated the README clone command URL.

v1.0.0

• Initial release.

📄 License

MIT — see obj.license in init.lua.