/sso-watcher — Hammerspoon SSO Auto-Picker

Automatically dismisses the Microsoft Entra ID / SSO account picker modal that appears inside Clawpilot (or any Electron app) by selecting the configured account and clicking Continue.

macOS only — uses Hammerspoon for Accessibility API access with zero TCC headaches.

How It Works

1. The SSO account picker is NOT inside Clawpilot — it's rendered by AppSSOAgent (com.apple.AppSSOAgent), the macOS Enterprise SSO broker from Company Portal
2. Hammerspoon polls AppSSOAgent's AX (Accessibility) tree every 3 seconds
3. Also triggers on any app activation (SSO agent may pop up for any app)
4. Looks for SSO dialog markers: "Accounts found", "Sign in to your account", etc.
5. Finds the AXRow containing the configured email and clicks it
6. Waits 0.8s then clicks the "Continue" button
7. 15-second cooldown after each successful click to avoid loops

Files

Installation

Run the install script with the target Microsoft account email:

bash "$HOME/customer-skills/sso-watcher/install.sh" user@microsoft.com

Or for a custom app name:

bash "$HOME/customer-skills/sso-watcher/install.sh" user@microsoft.com "MyElectronApp"

The installer:

1. Installs Hammerspoon via Homebrew (if missing)
2. Copies sso-watcher.lua to ~/.hammerspoon/
3. Creates config with the account email
4. Adds require("sso-watcher") to ~/.hammerspoon/init.lua
5. Enables Hammerspoon auto-launch at login
6. Launches/reloads Hammerspoon

macOS Permissions

After installation, Hammerspoon needs Accessibility access:

System Settings → Privacy & Security → Accessibility → Toggle ON: Hammerspoon

Without this, the watcher cannot read or interact with the SSO dialog.

Uninstallation

bash "$HOME/customer-skills/sso-watcher/uninstall.sh"

Removes the module, config, and log. Does NOT uninstall Hammerspoon itself.

Configuration

Edit ~/.hammerspoon/sso-watcher-config.lua:

return {
    account       = "user@microsoft.com",   -- email to auto-select
    poll_interval = 3,                       -- seconds between checks
    cooldown      = 15,                      -- seconds after successful click
    log_file      = os.getenv("HOME") .. "/Scripts/sso-watcher-hammerspoon.log",
}

The watcher always monitors AppSSOAgent (com.apple.AppSSOAgent) — the system SSO broker. No need to configure which app triggers the SSO dialog.

After editing, reload Hammerspoon: click the Hammerspoon menu bar icon → Reload Config, or run hs -c "hs.reload()" from terminal.

Troubleshooting

Watcher not triggering

1. Check Hammerspoon is running: look for the hammer icon in the menu bar
2. Check Accessibility: System Settings → Privacy & Security → Accessibility → Hammerspoon must be ON
3. Check logs: tail -f ~/Scripts/sso-watcher-hammerspoon.log
4. Check config: cat ~/.hammerspoon/sso-watcher-config.lua — verify the email is correct
5. Reload: Click Hammerspoon menu bar → Reload Config

"SSO markers found but account element not found"

The dialog was detected but your email wasn't in the AX tree yet. This is usually a timing issue — the watcher will retry on the next poll (3s).

Account clicked but Continue button not found

The 0.8s delay may not be enough on a slow machine. Edit the config to increase cooldown or modify sso-watcher.lua to increase the doAfter delay.

Skill Invocation

When the user asks to install or manage the SSO watcher via Clawpilot:

Install (first time on a new Mac)

1. Detect the user's Microsoft email:

   m365_get_my_profile() → email

   Or ask the user.
2. Run the installer:

   bash "$HOME/customer-skills/sso-watcher/install.sh" "user@microsoft.com"

3. Remind the user to grant Accessibility to Hammerspoon.

Check status

pgrep -x Hammerspoon && echo "Running" || echo "Not running"
cat ~/.hammerspoon/sso-watcher-config.lua
tail -5 ~/Scripts/sso-watcher-hammerspoon.log

Change account

bash "$HOME/customer-skills/sso-watcher/install.sh" "newemail@microsoft.com"

Uninstall

bash "$HOME/customer-skills/sso-watcher/uninstall.sh"

Prerequisite Auto-Install

This skill has no sibling skill dependencies. It only requires:

The install script handles Hammerspoon installation automatically.

Platform Note

This skill is macOS only. Hammerspoon does not exist on Linux or Windows. On other platforms, the SSO picker must be handled differently (e.g., browser extension, AutoHotkey on Windows).