Skip to main content

​
installation & startup

​
screenpipe won’t start

macOS:
  • grant screen recording permission: System Settings → Privacy & Security → Screen Recording → enable screenpipe
  • grant accessibility permission: System Settings → Privacy & Security → Accessibility → enable screenpipe
  • if you see “app is damaged”, right-click the app → Open (bypasses Gatekeeper on first launch)
Windows:
  • run as administrator on first launch
  • if Windows Defender blocks it, click “More info” → “Run anyway”
  • ensure .NET runtime is installed (screenpipe installer usually handles this)
Linux:
  • install dependencies: sudo apt install tesseract-ocr libxcb1
  • grant screen capture permissions for your display server (X11 or Wayland)

​
screenpipe is running but not capturing

check the health endpoint: 
curl http://localhost:3030/health
if it returns an error:
  • make sure screen recording permission is granted
  • restart the app
  • check if another instance is already running on port 3030
if health returns OK but search returns no results:
  • wait 1-2 minutes — screenpipe needs time to capture and process frames
  • check that your display is listed in settings → monitors
  • verify OCR is working: curl "http://localhost:3030/search?limit=1"

​
audio & transcription

​
no audio being captured

  • check settings → recording — make sure at least one device is selected
  • on macOS: grant microphone permission in System Settings → Privacy & Security → Microphone
  • verify audio is being recorded: curl "http://localhost:3030/search?content_type=audio&limit=1"

​
bluetooth headphone audio quality drops

this is a macOS limitation, not a screenpipe bug. when any app opens a bluetooth microphone, macOS switches from A2DP (high quality) to HFP (phone quality). fix: go to settings → recording → switch input to your MacBook’s built-in microphone. screenpipe still captures your voice, and your bluetooth audio quality stays high. note: AirPods don’t have this issue — Apple uses a proprietary codec.

​
transcription is inaccurate

  • switch to a better engine: settings → AI models → whisper-large-v3-turbo (most accurate)
  • set your language explicitly in settings (auto-detect is slower and less accurate)
  • reduce background noise
  • use a better microphone
  • try deepgram or screenpipe-cloud for cloud-based transcription (highest accuracy)

​
pipes

​
pipe runs but produces no output

  1. check logs: go to settings → pipes → click your pipe → view logs
  2. make sure your prompt includes concrete instructions to write output or send notifications
  3. test manually: click “run” in the pipe UI and watch the logs in real-time
  4. verify screenpipe has data to work with: curl "http://localhost:3030/search?limit=5"

​
pipe doesn’t run on schedule

  • make sure the pipe is enabled (toggle is on in settings → pipes)
  • check that the schedule format is correct: every 30m, every 2h, daily, or a cron expression
  • only one pipe runs at a time — if another pipe is running, yours will wait in the queue

​
pipe fails with AI errors

  • check your AI provider is configured: settings → AI settings
  • if using screenpipe cloud: make sure you’re signed in
  • if using your own API key: verify it’s valid and has credits
  • if using ChatGPT/Claude subscription: try signing out and back in to refresh tokens
  • check the pipe logs for the specific error message

​
pipe can’t find screen data

  • make sure screenpipe is actively recording (check health endpoint)
  • the pipe only searches within its schedule interval — if schedule is “every 30m”, it only looks at the last 30 minutes
  • verify data exists for the time range: curl "http://localhost:3030/search?start_time=30m+ago&limit=5"

​
MCP & AI connections

​
MCP not connecting to Claude/Cursor

  1. verify screenpipe is running: curl http://localhost:3030/health
  2. restart Claude Desktop / Cursor after adding the MCP config
  3. test the MCP server directly: npx @modelcontextprotocol/inspector npx screenpipe-mcp
  4. check that Node.js >= 18 is installed: node --version

​
Claude/Cursor says “no results” when asking about screen

  • make sure screenpipe has been running long enough to capture data
  • try a broader query: “what apps have I been using?” instead of very specific text
  • check that screen recording permissions are granted

​
ChatGPT connection not working

  • sign out and sign back in (settings → model selector → sign out)
  • make sure your ChatGPT subscription is active
  • try restarting the screenpipe app

​
performance

​
screenpipe using too much CPU

  • reduce capture FPS: settings → capture rate (default 1 FPS is usually fine)
  • exclude heavy apps from capture: settings → recording → ignored windows
  • on older machines, use whisper-tiny instead of whisper-large-v3-turbo

​
screenpipe using too much disk space

  • screenpipe uses ~30 GB/month at 1 FPS — this is normal
  • reduce capture rate in settings
  • data is stored in ~/.screenpipe/data/ — you can delete old recordings
  • future: cloud archive offloads older data (learn more →)

​
screenpipe using too much RAM

  • typical usage is ~600 MB RAM
  • if it’s using significantly more, restart the app
  • close the timeline view if you’re not using it (it loads video frames)

​
still stuck?

  1. check the FAQ for quick answers
  2. search GitHub issues — someone may have hit the same problem
  3. join our Discord — 10k+ members who can help debug
when asking for help, include:
  • your OS and version
  • screenpipe version (shown in settings)
  • output of curl http://localhost:3030/health
  • relevant pipe logs or error messages