Skip to content

macOS permissions

chatwire requires two macOS privacy grants to function. Both must be given to the specific Python binary that chatwire runs as — the path shown in chatwire doctor.

Quick summary

Permission Required Purpose
Full Disk Access Yes Read ~/Library/Messages/chat.db
Automation → Messages Yes Send messages via AppleScript
Contacts Recommended Resolve phone/email → display names
Accessibility No Not used by chatwire

Both critical permissions must show ✓ in chatwire doctor before the bridge can relay messages.

Full Disk Access

Why it's needed

~/Library/Messages/chat.db is in a TCC-protected directory. Without Full Disk Access, the Python process gets "permission denied" when it opens the database — and the bridge sees no messages.

How to grant (macOS 13 Ventura and later)

  1. Open System Settings → Privacy & Security → Full Disk Access
  2. Click the lock icon at the bottom-left and authenticate
  3. Click + (add)
  4. In the file picker, press Cmd+Shift+G and paste the path to the Python binary:
  5. pipx install: ~/.local/pipx/venvs/chatwire/bin/python3.13 (adjust minor version)
  6. python.org + pipx: /Library/Frameworks/Python.framework/Versions/3.13/bin/python3.13
  7. uv: ~/.local/share/uv/tools/chatwire/bin/python3.13
  8. Homebrew: /opt/homebrew/bin/python3 (Apple Silicon) or /usr/local/bin/python3 (Intel)
  9. Toggle the entry on (blue checkbox)
  10. Return to the terminal and run chatwire doctor

How to grant (macOS 12 Monterey)

Same process, but the app is called System Preferences (not System Settings). Navigate to System Preferences → Security & Privacy → Privacy → Full Disk Access.

Finding the exact binary path

Run chatwire doctor — it prints the Python binary path in the "Python" check line. That path is the exact binary that needs FDA.

If you don't have chatwire installed yet, use this to find the pipx venv Python:

ls ~/.local/pipx/venvs/chatwire/bin/python*

Automation → Messages

Why it's needed

The bridge sends iMessages via AppleScript:

chatwire bridge → osascript → Messages.app → iMessage/SMS

The Automation permission allows the Python binary to control Messages.app via Apple Events.

How to grant

  1. Open System Settings → Privacy & Security → Automation
  2. Find your Python binary in the list and expand it
  3. Check the box next to Messages

If Python doesn't appear in the list yet, trigger the first prompt:

  1. Open Script Editor (in Applications/Utilities)
  2. Paste and run: tell application "Messages" to get every service
  3. macOS will show a permission dialog — allow it
  4. Python should now appear in the Automation list

Verify

chatwire doctor
#   ✓ Automation → Messages

Without Contacts access, chatwire shows raw phone numbers and email addresses instead of display names. The bridge functions correctly, but the web UI is harder to use.

How to grant

  1. Open System Settings → Privacy & Security → Contacts
  2. Find your Python binary and toggle it on

chatwire reads the Contacts database directly from: 

~/Library/Application Support/AddressBook/Sources/*/AddressBook-v22.abcddb

This is a read-only file access — chatwire never modifies Contacts.

The TCC identity problem

macOS TCC tracks each Python binary as a distinct identity using its code signature and path. This means:

  • A python.org Python binary and a Homebrew Python binary are different identities, even on the same machine.
  • Granting FDA to python.org's Python does not grant FDA to Homebrew's Python.
  • Upgrading Python to a new minor version (3.12 → 3.13) creates a new binary path — you must re-grant.

Checking which binary needs the grant

chatwire doctor

Look for the line: 

  ✓ Python — 3.13.x ≥ 3.10

The binary path is what needs the grant, not the version number.

After upgrading Python

If you install a new Python version and the old one is no longer at the same path:

  1. Run chatwire doctor to see the new binary path
  2. Go to System Settings → Privacy & Security → Full Disk Access
  3. Remove the old entry (toggle off, then click -)
  4. Add the new binary path with +
  5. Repeat for Automation → Messages
  6. Restart the bridge: launchctl kickstart -k gui/$(id -u)/dev.chatwire.bridge

TCC reset (troubleshooting)

If you need to start fresh with permissions:

# Reset Full Disk Access grants
tccutil reset SystemPolicyAllFiles

# Reset Automation grants
tccutil reset AppleEvents

These commands remove all FDA or Automation grants for all apps — not just chatwire. After resetting, re-grant the permission to the chatwire Python binary.

Note: tccutil reset may require disabling SIP (System Integrity Protection) on some macOS versions. Use it only when the normal grant process isn't working.

Setup wizard permissions step

The web setup wizard at http://127.0.0.1:8723/setup shows the current permission status and has Open Settings buttons that deep-link to the correct pane. The wizard page auto-polls every 30 seconds, so once you grant a permission and return to the browser, the check turns green automatically.

See First run for the full wizard walkthrough.