permiso-accessibility-permissions

# Permiso — macOS Permission Dialog Helper

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Permiso provides a polished permission dialog UI for macOS apps that guides users through enabling accessibility and privacy settings — replicating the guided flow seen in OpenAI's Codex Computer Use product.

## What It Does

- Presents an animated, guided overlay panel directing users to open System Settings and enable specific permissions (e.g. Accessibility)
- Mirrors the UX pattern from Codex Computer Use: an on-screen assistant that walks users through enabling access
- Handles the common friction point of macOS permission flows with a clear, app-integrated UI

## Installation

### Swift Package Manager

Add to your `Package.swift`:

```swift
dependencies: [
    .package(url: "https://github.com/zats/permiso", branch: "main")
]
```

Or in Xcode: **File → Add Package Dependencies** → enter `https://github.com/zats/permiso`

Then add `Permiso` to your target's dependencies:

```swift
.target(
    name: "YourApp",
    dependencies: ["Permiso"]
)
```

## Core API

### Basic Usage

```swift
import Permiso

@MainActor
func showAccessibilityHelper() {
    PermisoAssistant.shared.present(panel: .accessibility)
}
```

### Triggering on App Launch

```swift
import SwiftUI
import Permiso

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .onAppear {
                    checkAndRequestAccessibility()
                }
        }
    }

    @MainActor
    func checkAndRequestAccessibility() {
        let trusted = AXIsProcessTrusted()
        if !trusted {
            PermisoAssistant.shared.present(panel: .accessibility)
        }
    }
}
```

### AppDelegate Pattern

```swift
import AppKit
import Permiso

class AppDelegate: NSObject, NSApplicationDelegate {
    func applicationDidFinishLaunching(_ notification: Notification) {
        requestAccessibilityIfNeeded()
    }

    @MainActor
    func requestAccessibilityIfNeeded() {
        guard !AXIsProcessTrusted() else { return }
        PermisoAssistant.shared.present(panel: .accessibility)
    }
}
```

## Common Patterns

### Check Permission Before Sensitive Actions

```swift
import Permiso
import ApplicationServices

@MainActor
func performAccessibilityAction() {
    guard AXIsProcessTrusted() else {
        PermisoAssistant.shared.present(panel: .accessibility)
        return
    }
    // Proceed with accessibility-dependent work
    doAccessibilityWork()
}
```

### Polling for Permission Grant

```swift
import Permiso
import ApplicationServices
import Combine

class PermissionMonitor: ObservableObject {
    @Published var isAccessibilityGranted = false
    private var timer: AnyCancellable?

    @MainActor
    func startMonitoring() {
        if AXIsProcessTrusted() {
            isAccessibilityGranted = true
            return
        }

        PermisoAssistant.shared.present(panel: .accessibility)

        timer = Timer.publish(every: 1.0, on: .main, in: .common)
            .autoconnect()
            .sink { [weak self] _ in
                if AXIsProcessTrusted() {
                    self?.isAccessibilityGranted = true
                    self?.timer?.cancel()
                }
            }
    }
}
```

### SwiftUI View Integration

```swift
import SwiftUI
import Permiso

struct SettingsView: View {
    @State private var accessibilityGranted = AXIsProcessTrusted()

    var body: some View {
        VStack(spacing: 16) {
            HStack {
                Image(systemName: accessibilityGranted ? "checkmark.circle.fill" : "xmark.circle.fill")
                    .foregroundColor(accessibilityGranted ? .green : .red)
                Text("Accessibility Access")
            }

            if !accessibilityGranted {
                Button("Enable Accessibility Access") {
                    requestAccess()
                }
                .buttonStyle(.borderedProminent)
            }
        }
        .padding()
        .onReceive(Timer.publish(every: 2, on: .main, in: .common).autoconnect()) { _ in
            accessibilityGranted = AXIsProcessTrusted()
        }
    }

    @MainActor
    func requestAccess() {
        PermisoAssistant.shared.present(panel: .accessibility)
    }
}
```

## Requirements

- **macOS**: The library targets macOS (version as specified by the package; check for macOS 13+ for best compatibility)
- **Swift**: Swift 5.9+
- **Main Actor**: `PermisoAssistant.shared.present(panel:)` must be called from the main thread / `@MainActor` context

## Entitlements / Info.plist

For accessibility usage, ensure your app's `Info.plist` includes a usage description (though macOS doesn't require this like iOS, it's good practice), and that your app is **not sandboxed** or has the correct entitlements if it needs to use accessibility APIs:

```xml
<!-- In your .entitlements file if needed -->
<key>com.apple.security.temporary-exception.apple-events</key>
<true/>
```

For apps that actually use accessibility features after permission is granted:

```swift
// Request trust prompt (system dialog) alongside Permiso's guided UI
let options = [kAXTrustedCheckOptionPrompt.takeRetainedValue(): true] as CFDictionary
AXIsProcessTrustedWithOptions(options)
```

## Troubleshooting

**Panel doesn't appear**
- Ensure you're calling from `@MainActor` / main thread
- Check that your app has a visible window; the panel attaches to the app's UI context

**`AXIsProcessTrusted()` returns false even after granting**
- macOS caches trust state; the app may need to be relaunched or the check polled with a timer (see polling pattern above)
- Some sandboxed apps require a full app restart after granting accessibility

**Build errors: `cannot find 'PermisoAssistant' in scope`**
- Confirm `import Permiso` is at the top of the file
- Confirm the package is added to the correct target in Xcode, not just the project

**Panel appears but dismisses immediately**
- Make sure you're not overriding the window or calling dismiss logic right after present
- Avoid calling present inside a `Task { }` that gets cancelled immediately

## Key Types Reference

| Type | Description |
|------|-------------|
| `PermisoAssistant` | Singleton entry point — use `.shared` |
| `PermisoAssistant.shared.present(panel:)` | Shows the guided permission dialog |
| `.accessibility` | Panel type for Accessibility settings |