Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.screenpi.pe/llms.txt

Use this file to discover all available pages before exploring further.

screenpipe needs macOS Screen Recording permission to capture frames and run OCR on what you see. if the engine fails to start with a permission error — including the “engine stuck” screen during onboarding — this page walks through every recovery path.

​
grant it (the normal path)

  1. open System Settings → Privacy & Security → Screen & System Audio Recording.
  2. toggle screenpipe ON. macOS will prompt you to quit and reopen — click Quit & Reopen.
  3. restart screenpipe. the engine should start within a few seconds.
the in-app “open system settings” button on the stuck screen jumps straight to this pane.

​
if you switched build channels

macOS’s TCC database (transparency, consent & control) tracks Screen Recording permission per bundle id, not per app name. if you previously granted permission to one build and switched to another, the new build looks like a brand new app to macOS — your earlier grant doesn’t apply. screenpipe ships under four bundle ids:
bundle idchannel
screenpi.peproduction (stable release)
screenpi.pe.betabeta channel
screenpi.pe.devlocal dev build (cargo / bun tauri dev)
screenpi.pe.enterpriseenterprise distribution
the stuck screen shows which one you’re running as. if it doesn’t match the entry you’ve toggled in System Settings, you need to grant permission for the new bundle id. this is the single most common cause of “engine stuck” during onboarding — confirmed by telemetry showing 90% of stuck users have no boot phase reported, which is exactly the signature of a permission rejection at spawn time.

​
reset and re-request

when the permission is in a wedged terminal state — screenpipe shows in System Settings but toggling does nothing, or it doesn’t show at all — wipe the TCC record for that bundle id and re-trigger the prompt. the in-app reset & re-request button does this for you. it runs: 
tccutil reset ScreenCapture <your-bundle-id>
you can run it manually from Terminal too. for each bundle id you have installed: 
# production build
tccutil reset ScreenCapture screenpi.pe

# beta channel
tccutil reset ScreenCapture screenpi.pe.beta

# local dev build
tccutil reset ScreenCapture screenpi.pe.dev

# enterprise distribution
tccutil reset ScreenCapture screenpi.pe.enterprise
no sudo required — TCC’s per-app records live in your user scope. after reset, relaunch screenpipe. macOS will prompt fresh.

​
nuclear option

if per-bundle resets don’t recover, wipe every app’s Screen Recording grant in one shot: 
tccutil reset ScreenCapture
this affects every screen-recording app on your machine (zoom, OBS, cleanshot, etc.) — they’ll all re-prompt on next launch. only use this if the scoped resets above failed. screen recording is the most failure-prone, but screenpipe also asks for:
  • microphone — for audio capture. System Settings → Privacy & Security → Microphone. reset: tccutil reset Microphone <bundle-id>
  • accessibility — for app/window context. System Settings → Privacy & Security → Accessibility. reset: tccutil reset Accessibility <bundle-id>
  • input monitoring — for keystrokes (optional). System Settings → Privacy & Security → Input Monitoring. reset: tccutil reset ListenEvent <bundle-id>
the same per-bundle-id rules apply to all of these.

​
still stuck?

send logs from the stuck screen (the send logs button uploads them so the team can grep). or book a slot at cal.com/team/screenpipe/chat. see also: general troubleshooting, FAQ.