# macOS Permissions Guide

OpenAdapt requires several system permissions on macOS to capture user interactions and replay actions. This guide covers the required permissions and how to enable them.

**Compatibility**: macOS 13 Ventura, macOS 14 Sonoma, and macOS 15 Sequoia. Earlier versions may have different menu layouts.

## Overview

OpenAdapt needs three types of permissions:

| Permission | Purpose | Required For |
|------------|---------|--------------|
| **Input Monitoring** | Capture keyboard and mouse input | Recording user actions |
| **Screen Recording** | Capture screenshots | Recording screen state |
| **Accessibility** | Control mouse and keyboard | Replaying actions |

**Important**: While macOS will prompt you for Input Monitoring and Screen Recording permissions on first run, it will **not** prompt for Accessibility permissions. If Accessibility permission is not granted, action replay will fail silently.

## Which Application Needs Permissions?

Grant permissions to the application you use to run OpenAdapt:

- **Terminal.app** - If you run OpenAdapt from the built-in macOS Terminal
- **iTerm** - If you use iTerm2 as your terminal
- **Visual Studio Code** - If you run from the VS Code integrated terminal
- **PyCharm** or **other IDE** - If you run from an IDE's terminal
- **Python** - In some cases, the Python executable itself may need permissions

**Tip**: If permissions don't seem to work, try granting them to both your terminal application and the Python executable.

## Enabling Input Monitoring

Input monitoring allows OpenAdapt to capture keyboard and mouse events during recording.

1. Open **System Settings** (or System Preferences on older macOS)
2. Navigate to **Privacy & Security** in the sidebar
3. Click **Input Monitoring** in the right panel
4. Click the **+** button to add your terminal application
5. Toggle the switch to enable access

![Enabling input monitoring](assets/macOS_input_monitoring.png)

## Enabling Screen Recording

Screen recording allows OpenAdapt to capture screenshots during recording.

1. Open **System Settings**
2. Navigate to **Privacy & Security** in the sidebar
3. Click **Screen Recording** in the right panel
4. Click the **+** button to add your terminal application
5. Toggle the switch to enable access
6. You may need to restart your terminal for changes to take effect

![Enabling screen recording](assets/macOS_screen_recording.png)

## Enabling Accessibility (for Action Replay)

Accessibility permissions allow OpenAdapt to control the mouse and keyboard during replay.

**Note**: This permission is required for replaying recorded actions. Without it, replay will fail silently.

1. Open **System Settings**
2. Navigate to **Privacy & Security** in the sidebar
3. Click **Accessibility** in the right panel
4. Click the **+** button to add your terminal application
5. Toggle the switch to enable access

![Enabling accessibility](assets/macOS_accessibility.png)

## Quick Access via Terminal

You can quickly open the Privacy & Security settings from the command line:

```bash
# Open Privacy & Security settings
open "x-apple.systempreferences:com.apple.preference.security?Privacy"

# Open Input Monitoring directly
open "x-apple.systempreferences:com.apple.preference.security?Privacy_ListenEvent"

# Open Screen Recording directly
open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"

# Open Accessibility directly
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
```

## Troubleshooting

### Permission prompts not appearing

If you don't see a permission prompt when running OpenAdapt:

1. Check if the permission is already granted in System Settings
2. Try removing and re-adding the application in the permissions list
3. Restart your terminal application
4. Restart your Mac if issues persist

### Replay actions not working

If recording works but replay does not:

1. Verify Accessibility permission is granted
2. Check that the correct application has the permission
3. Try granting permission to both your terminal and the Python executable

### Screen recording shows black screenshots

1. Ensure Screen Recording permission is granted
2. Restart your terminal application after granting permission
3. Some applications may require a system restart

### Finding the Python executable

If you need to grant permissions to Python directly:

```bash
# Find which Python is being used
which python

# Or for Python 3 specifically
which python3

# If using a virtual environment, it will show the venv path
# Grant permissions to that specific Python executable
```

## Usage with New Modular Architecture

When using the new OpenAdapt modular packages (v1.0.0+):

```bash
# Recording (requires Input Monitoring + Screen Recording)
openadapt capture start --name "my-task"

# Replaying (requires Accessibility)
openadapt replay --strategy visual
```

The CLI commands are run from your terminal, so ensure your terminal application has the necessary permissions.

## Related Documentation

- [Legacy Codebase Freeze](./LEGACY_FREEZE.md) - Information about the transition to the new modular architecture
- [OpenAdapt Documentation](https://github.com/OpenAdaptAI/OpenAdapt) - Main project documentation
