macOS Permissions

Grant Accessibility permissions to enable keystroke tracking

TypeSteps requires macOS Accessibility permissions to track your typing activity. This guide explains why these permissions are needed and how to grant them.

Why Accessibility Permissions?

TypeSteps uses macOS Accessibility APIs to:

• Monitor global keyboard events across all applications
• Count keystrokes in real-time
• Track which applications you’re typing in
• Identify project names from window titles
• Provide accurate typing statistics

Privacy First: TypeSteps only counts keystrokes. It does NOT record or store what you type. All data stays on your Mac.

Granting Permissions

First Launch (Onboarding)

When you first launch TypeSteps, you’ll see an onboarding flow:

1. Welcome Screen

   The app will explain what permissions are needed and why

2. Permission Prompt

   Click Grant Permission to open System Settings

   TypeSteps will call:

   let options = [kAXTrustedCheckOptionPrompt.takeUnretainedValue() as String: true]
   let trusted = AXIsProcessTrustedWithOptions(options as CFDictionary)
   

   This triggers the macOS permission prompt automatically.

3. System Settings Opens

   macOS will open System Settings > Privacy & Security > Accessibility

4. Enable TypeSteps

   1. Find TypeSteps in the list
   2. Toggle the switch to ON
   3. You may need to unlock with your password or Touch ID

   If TypeSteps isn’t in the list, try clicking the + button and manually adding the TypeSteps app from your Applications folder.

5. Return to TypeSteps

   Once enabled, return to TypeSteps. The app will automatically detect the permission change and start tracking.

Manual Permission Check

If you need to verify or re-enable permissions later:

1. Open System Settings (or System Preferences on older macOS)
2. Go to Privacy & Security
3. Select Accessibility from the sidebar
4. Locate TypeSteps in the list
5. Ensure the toggle is ON

Permission States

TypeSteps checks permissions in two ways:

Interactive Check

Used during onboarding (KeystrokeListener.swift:15-21):

func checkPermissions() {
    let options = [kAXTrustedCheckOptionPrompt.takeUnretainedValue() as String: true]
    let trusted = AXIsProcessTrustedWithOptions(options as CFDictionary)
    DispatchQueue.main.async {
        self.isAuthorized = trusted
    }
}

This will show the system prompt if permissions aren’t granted.

Silent Check

Used when the app starts automatically (KeystrokeListener.swift:23-29):

func checkPermissionsSilently() -> Bool {
    let trusted = AXIsProcessTrusted()
    DispatchQueue.main.async {
        self.isAuthorized = trusted
    }
    return trusted
}

This checks without prompting, used when app launches at login.

How Tracking Works

Once permissions are granted, TypeSteps:

1. Starts Global Event Monitor: Listens to all keyboard events system-wide
2. Filters Valid Characters: Only counts letters, numbers, punctuation, and whitespace
3. Tracks Context: Identifies the active application and project
4. Respects Privacy: Never stores the actual characters typed

From KeystrokeListener.swift:31-36:

func startListening() {
    guard eventMonitor == nil else { return }
    eventMonitor = NSEvent.addGlobalMonitorForEvents(matching: .keyDown) { event in
        self.handle(event: event)
    }
}

Troubleshooting Permissions

Permission Prompt Not Showing

Solution Steps

1. Quit TypeSteps completely
2. Open System Settings > Privacy & Security > Accessibility
3. Remove TypeSteps from the list (click - button)
4. Restart your Mac
5. Launch TypeSteps again - the prompt should appear

TypeSteps Not in Accessibility List

Manual Addition

1. Open System Settings > Privacy & Security > Accessibility
2. Click the lock icon to unlock (enter password)
3. Click the + button
4. Navigate to Applications folder
5. Select TypeSteps.app
6. Click Open
7. Toggle it ON

Permission Granted But Not Tracking

Verification Steps

1. Check that TypeSteps is in the Accessibility list and enabled
2. Restart TypeSteps completely (Quit from menu bar, relaunch)
3. Verify tracking isn’t paused (menu bar shows keyboard icon, not keyboard.badge.ellipsis)
4. Open TypeSteps dashboard to see real-time counts
5. Type something - the count should increase immediately

If still not working, see Troubleshooting Guide.

Permission Revoked After macOS Update

Reset Permissions

Sometimes macOS updates reset app permissions:

1. Open System Settings > Accessibility
2. Toggle TypeSteps OFF then ON again
3. Restart TypeSteps
4. If that doesn’t work, remove and re-add TypeSteps to the list

Security & Privacy

TypeSteps takes your privacy seriously:

What TypeSteps DOES track:

• Number of keystrokes (count only)
• Application names where you type
• Project names (from window titles)
• Timestamps of typing activity

What TypeSteps DOES NOT track:

• The actual text you type
• Passwords or sensitive data
• Keystroke content or sequences
• Mouse movements or clicks

All data is stored locally on your Mac. Nothing is sent to external servers.

App Launch Behavior

TypeSteps handles permissions smartly when launching (TypeStepsApp.swift:16-28):

private func checkAndStartTracking() {
    let hasCompletedOnboarding = UserDefaults.standard.bool(forKey: "has_completed_onboarding")
    
    if hasCompletedOnboarding {
        // Only start if permission already granted
        if KeystrokeListener.shared.checkPermissionsSilently() {
            KeystrokeListener.shared.startListening()
        }
    } else {
        // Show onboarding flow
        NotificationCenter.default.post(name: .showOnboarding, object: nil)
    }
}

This ensures:

• Silent permission check on subsequent launches
• No annoying prompts after initial setup
• Automatic tracking start if permissions are valid

Next Steps

Troubleshooting

Fix common permission and tracking issues

Daily Goals

Start setting typing goals