macOS Permissions

Configure the system permissions SuperCmd needs to function

Overview

SuperCmd requires several macOS permissions to provide its core features. The app will prompt you for these permissions on first use, or you can grant them manually in System Settings → Privacy & Security.

You may need to restart SuperCmd after granting permissions for them to take effect.

Required Permissions

These permissions are essential for SuperCmd’s core functionality:

Accessibility

Why it’s needed:

• Window management (tiling, resizing, positioning)
• Snippet expansion (keyboard injection)
• Getting selected text from other apps

How to enable:

1. Open System Settings

   Go to System Settings → Privacy & Security → Accessibility

2. Add SuperCmd

   Click the + button and select SuperCmd from Applications

3. Enable the toggle

   Ensure SuperCmd is checked in the list

4. Restart SuperCmd

   Quit and relaunch the app

Without Accessibility permission, window management and snippet expansion will not work.

Technical details:

SuperCmd uses the macOS Accessibility API (AXIsProcessTrusted()) to:

• Query window positions and sizes
• Move and resize windows programmatically
• Inject keystrokes for snippet expansion
• Read selected text via AppleScript

Source: src/native/window-adjust.swift, src/native/snippet-expander.swift

---

Input Monitoring

Why it’s needed:

• Detect global keyboard shortcuts (launcher hotkey, hold-to-speak)
• Monitor modifier keys (Fn key for voice input)
• Per-command hotkeys

How to enable:

1. Open System Settings

   Go to System Settings → Privacy & Security → Input Monitoring

2. Add SuperCmd

   Click the + button and select SuperCmd

3. Enable the toggle

   Ensure SuperCmd is checked

4. Restart SuperCmd

   Quit and relaunch the app

Without Input Monitoring, the global hotkey (e.g., Alt+Space) will not work.

Technical details:

SuperCmd uses:

• CGEventTapCreate() to listen for global key events
• IOHIDManager to detect Fn key holds
• Electron’s globalShortcut API (requires Input Monitoring)

Source: src/native/hotkey-hold-monitor.swift, src/main/main.ts (globalShortcut registration)

---

Optional Permissions

These permissions enable additional features:

Microphone

Why it’s needed:

• Voice input (hold-to-speak dictation)
• Whisper speech-to-text

When it’s required:

• Only if you plan to use voice input features
• Prompted when you first try to use voice input

How to enable:

1. Open System Settings

   Go to System Settings → Privacy & Security → Microphone

2. Add SuperCmd

   Click the + button and select SuperCmd

3. Enable the toggle

   Ensure SuperCmd is checked

If you don’t use voice input, you can safely skip this permission.

Technical details:

SuperCmd uses:

• AVAudioEngine for audio capture
• SFSpeechRecognizer for native speech recognition
• OpenAI Whisper API for transcription (when configured)

Source: src/native/speech-recognizer.swift, src/main/ai-provider.ts (transcribeAudio)

---

Automation (AppleScript)

Why it’s needed:

• Get selected text from the frontmost app
• Get selected files in Finder
• Extension actions that use AppleScript

When it’s required:

• When extensions call getSelectedText() or getSelectedFinderItems()
• For extensions that automate other apps

How to enable:

1. Open System Settings

   Go to System Settings → Privacy & Security → Automation

2. Find SuperCmd

   Look for SuperCmd in the app list

3. Enable target apps

   Check the boxes for apps SuperCmd should automate (e.g., Finder, Safari)

macOS will automatically prompt you the first time SuperCmd tries to automate an app.

Technical details:

SuperCmd uses AppleScript to:

• Extract selected text: tell application "System Events" to get value of attribute "AXSelectedText"
• Get Finder selection: tell application "Finder" to get selection

Source: src/main/main.ts (IPC handler for get-selected-text)

---

Permission Summary

Permission	Required	Purpose
Accessibility	✅ Yes	Window management, snippet expansion
Input Monitoring	✅ Yes	Global hotkeys, launcher shortcut
Microphone	⚠️ Optional	Voice input, speech-to-text
Automation	⚠️ Optional	Selected text capture, Finder integration

Checking Permission Status

SuperCmd includes native helpers to check permission status:

Accessibility Check

// src/native/window-adjust.swift
if !AXIsProcessTrusted() {
  print("ERROR: Accessibility permission not granted")
  exit(1)
}

Microphone Check

// src/native/microphone-access.swift
let status = AVCaptureDevice.authorizationStatus(for: .audio)
if status != .authorized {
  print("not-authorized")
}

Input Monitoring Check

SuperCmd attempts to register a global shortcut and reports failure if Input Monitoring is missing.

Source: src/native/input-monitoring-request.swift

Troubleshooting

Global hotkey doesn't work

1. Open System Settings → Privacy & Security → Input Monitoring
2. Ensure SuperCmd is in the list and enabled
3. If not listed, remove and re-add it
4. Restart SuperCmd
5. Try a different hotkey combination in Settings

Window management doesn't work

1. Open System Settings → Privacy & Security → Accessibility
2. Ensure SuperCmd is enabled
3. If already enabled, uncheck and re-check the box
4. Restart SuperCmd
5. Test by searching for “Window Management” in the launcher

Voice input doesn't work

1. Check System Settings → Privacy & Security → Microphone
2. Ensure SuperCmd is enabled
3. Test microphone with another app (Voice Memos)
4. Check AI settings (must have Whisper configured)
5. Check /var/log/system.log for audio capture errors

'Permission denied' when trying to grant permissions

This usually means your macOS user account doesn’t have admin privileges:

1. Log in with an admin account
2. Grant permissions
3. Switch back to your standard account

Or use System Settings to promote your account to admin temporarily.

Permissions keep getting revoked

This can happen if:

1. The app signature changed (development builds vs. signed releases)
2. macOS security policy changed
3. The app was moved after permissions were granted

Solution: Remove SuperCmd from all permission lists, then re-add it.

Resetting Permissions

To completely reset all permissions:

# Remove SuperCmd from all permission databases
tccutil reset Accessibility com.supercmd.app
tccutil reset ListenEvent com.supercmd.app
tccutil reset Microphone com.supercmd.app
tccutil reset AppleEvents com.supercmd.app

You’ll need to re-grant all permissions after running these commands.

Next Steps

Settings

Configure app settings

AI Providers

Set up AI integrations

Hotkeys

Customize keyboard shortcuts

Troubleshooting

Common issues and solutions