| name | keychain-kill |
| description | Terminate macOS SecurityAgent and dismiss all stacked keychain modal prompts. Programmatically dismiss active macOS credential popups and debug headless/background keyring access issues (launchd, cron, isolated tmux test runners). Slash command: /keychain_kill. |
| scope | user |
macOS Keychain Kill & Headless Keyring Troubleshooting
Immediately dismiss all stacked macOS SecurityAgent credential popups by hard-killing their processes, then diagnose and fix the underlying headless keyring access issue.
1. Fast Dismissal (The Hard Kill)
When a headless process triggers keychain lookups, macOS launches SecurityAgent to request password entry from the user. If the process is backgrounded, it hangs recursively.
To immediately dismiss every active keychain popup across all displays and spaces, execute a hard kill on the on-demand system processes:
pkill -9 -f SecurityAgent || killall -9 SecurityAgent || true
pkill -9 -f universalAccessAuthWarn || true
Note: Terminates the system agent. macOS automatically cancels all pending authentication requests, immediately restoring a clean display state.
Run this hard kill FIRST, before any diagnostics, then inform the user that the keychain prompts have been dismissed.
2. Root Cause & Architectural Permanent Fix
Headless background agents (e.g. running under tmux or ai.hermes.prod launchd daemons) operate in separate security sessions where the user's main login keychain ($HOME/Library/Keychains/login.keychain-db) is locked. When SCM tools (gh, git, or claude authentication modules) attempt to check credentials, they query the locked login keychain, triggering the OS prompt.
Bypassing Keychain Lookups inside Background Workers
The permanent solution requires isolating background SCM operations from the locked GUI login keychain:
- Temporary Isolated Session Keychains:
Detect when Darwin processes execute inside a headless background workspace. Instead of attempting to symlink the locked login keychain, create a password-less, isolated temporary keychain under the session's workspace directory:
security create-keychain -p "" session.keychain
security unlock-keychain -p "" session.keychain
security default-keychain -s session.keychain
- CLI Storage Bypasses (
--bare):
Always pass the --bare option to processes (like claude --bare) that support bypassing secure local storage persistence.
- Automate Workspace Trust:
Pre-populate
trustedFolders.json under both the session and global configuration namespaces (e.g., ~/.claude/settings.json) to programmatically authorize newly cloned worktrees, preventing interactive trust prompts.
3. Diagnostic Procedures
If keychain prompts continue to appear, perform the following checks:
- Find Active Security Agents:
Verify if a lingering SecurityAgent process is currently active:
ps aux | grep -i SecurityAgent | grep -v "grep"
- Verify CLI Health & Non-Canonical Processes:
Run
ao doctor to ensure all active background workers inherit the canonical compiled environment. Terminate outdated processes carrying old environment configurations:
ao doctor --fix
Output
After running the hard kill, report to the user that keychain prompts have been dismissed. If prompts recur, walk through the diagnostic procedures above before proposing the isolated-session-keychain fix.
