---
title: macOS permissions
description: The TCC permissions Tadoru uses, and how tadoru doctor diagnoses and guides you through granting them.
---

Tadoru never records your screen. Instead, depending on what you capture (the `capture.sources` setting), it uses up to three macOS permissions (TCC).

## Required permissions

| Permission | System Settings item | Used for | Related event types |
| --- | --- | --- | --- |
| Accessibility | Accessibility | Window titles, focus, UI elements | `window.*` `ui.*` |
| Input Monitoring | Input Monitoring | Detecting keys, scrolling, clicks | `input.*` `ui.click` `clipboard.*` |
| Automation | Automation (per target app) | Reading the current URL and tab info from Chrome | `browser.navigate` |

Two important properties:

- **App launch, termination, and switching (`app.*`) require no permissions at all.** Even with zero permissions granted, Tadoru works as an app-level activity history.
- **A permission is only "required" when a source that needs it is enabled.** For example, with `input` removed from `capture.sources`, the diagnosis reports `ok` even if Input Monitoring is not granted.

## Diagnose with `doctor`

```bash
tadoru doctor
```

Checks the granted state of each permission against your current configuration. If anything is missing, it explains what to grant and which System Settings pane to use, then exits with **exit code 3**.

```bash
tadoru doctor --fix
```

`--fix` opens the System Settings pane for each missing permission directly (the granting itself is always your action).

### For agents and scripts: `--json`

```bash
tadoru doctor --json
```

```json
{
  "ok": false,
  "capture_sources": ["app", "window", "ui", "input", "browser"],
  "permissions": {
    "accessibility":     { "status": "granted" },
    "input_monitoring":  { "status": "denied", "required_for": ["input.key", "input.scroll", "clipboard.copy", "clipboard.paste", "ui.click"] },
    "automation":        { "per_app": { "com.google.Chrome": "not_determined" } }
  },
  "missing_required": ["input_monitoring"],
  "settings_pane": "x-apple.systempreferences:com.apple.preference.security?Privacy_ListenEvent"
}
```

`status` is one of `granted` / `denied` / `not_determined`. Because missing permissions are signaled with the dedicated exit code **3**, agents and scripts can recognize "this is a permission problem" without parsing output (see [exit codes](/reference/cli#exit-codes)).

## Granting manually

Enable `tadoru` under System Settings → **Privacy & Security**:

| Permission | Location |
| --- | --- |
| Accessibility | Privacy & Security → Accessibility |
| Input Monitoring | Privacy & Security → Input Monitoring |
| Automation | Privacy & Security → Automation (also confirmed via a dialog on the first Apple Event) |

## Permissions and code signing

macOS ties permissions to the **code-signing identity of the executable**. Release binaries are signed and notarized, giving them a stable signing identity — **granted permissions survive upgrades** even though the binary is replaced. Homebrew distribution is still in preparation; for now, Tadoru is installed by building from source (see the warning below).

:::warning[Building from source]
A self-built binary has a different signing identity, so you may need to re-grant permissions after each rebuild. Plan for this during development.
:::

## What Tadoru will not do

- It never grants permissions automatically or touches the TCC database (macOS makes this impossible by design). Tadoru's scope is **detection, guidance, and diagnosis** only.
- If `start` detects missing permissions, it refuses to start recording and exits with code 3 explaining what is missing. It never silently runs in a half-working state.