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.
when a pipe fails, debug it like a small production job: confirm the engine is alive, confirm the pipe has data, confirm the AI provider works, then inspect logs and permissions.
fast triage
| check | command or screen | what it tells you |
|---|
| engine | curl http://localhost:3030/health | screenpipe API is alive |
| data | curl "http://localhost:3030/search?limit=5" | there is searchable context |
| pipe list | curl http://localhost:3030/pipes | pipe is installed and enabled |
| logs | curl http://localhost:3030/pipes/<name>/logs | last stdout, stderr, and errors |
| manual run | curl -X POST http://localhost:3030/pipes/<name>/run | schedule is not the blocker |
| stop | curl -X POST http://localhost:3030/pipes/<name>/stop | clears a stuck execution |
lifecycle
common failures
| symptom | likely cause | fix |
|---|
| run never starts | pipe disabled or another run is queued | enable it, stop stale runs, run manually |
| no useful output | prompt did not require a durable output | tell the pipe exactly where to write, notify, or summarize |
| ”connection refused” | local API still booting | wait for /health, then rerun |
| ”unauthorized” | API auth or provider key missing | set SCREENPIPE_API_KEY, sign in, or update provider credentials |
| empty search results | time range too narrow or capture disabled | widen the window and verify /search?limit=5 |
| Windows terminal flashes and closes | process crashed immediately | open pipe logs or run script from PowerShell |
| pipe sees old data only | schedule window or stale filters | remove filters, run manually, widen time range |
| custom window not found | exact window title differs | search broad, then inspect stored window_name |
| notification does not fire | condition, integration, or OS notification setting | test each step outside the pipe |
| provider timeout | model slow, batch too large, or network issue | use faster model, add timeout, or rerun |
| connection API fails | integration disconnected or missing proxy path | reconnect the integration and use /connections/<id>/proxy/... |
| permission denied | pipe permissions too narrow | update pipe-permissions allowlist |
- open settings -> pipes -> your pipe -> logs.
- run the pipe manually.
- if the pipe calls a script, run that script directly in PowerShell.
- confirm
pipe.md exists in the pipe folder and has valid frontmatter.
- confirm the local API is alive:
curl http://localhost:3030/health
curl "http://localhost:3030/search?limit=5&content_type=all"
write prompts with debuggable outputs
weak:
Tell me what I did today.
Search the last 24 hours of screenpipe data.
Write a markdown summary to ~/Documents/daily-screenpipe-summary.md.
Include:
- accomplishments
- meetings
- open loops
- timeline links for the 5 most important moments
If there is no data, say which API call returned empty.
Search the last 10 minutes for the window named "Operations Dashboard".
If you find a red error banner, send a desktop notification.
If the window is missing or no error is visible, write a log line explaining which case happened.
Never send an alert unless the evidence is present in screenpipe results.
frontmatter checklist
---
schedule: every 30m
enabled: true
timeout: 600
permissions:
allow:
- /search
- /activity-summary
- /meetings
---
secrets and provider auth
do:
- keep API keys in
.env next to pipe.md
- use connected app proxies when possible
- use local models through Ollama for fully local execution
- use
SCREENPIPE_API_KEY when API auth is enabled
do not:
- paste API keys into the prompt body
- ask the AI to print secrets
- grant broad write access before the pipe is proven
connection proxies
connected apps can be called without exposing secrets to the pipe prompt:
curl "http://localhost:3030/connections/gmail/proxy/users/me/messages"
curl "http://localhost:3030/connections/notion/proxy/v1/search"
curl "http://localhost:3030/connections/hubspot/proxy/crm/v3/objects/contacts"
search filters that usually break custom pipes
start with broad search, then add filters one at a time.
curl "http://localhost:3030/search?limit=10&content_type=all"
curl "http://localhost:3030/search?limit=10&content_type=accessibility"
curl "http://localhost:3030/search?limit=10&content_type=ocr"
curl "http://localhost:3030/search?limit=10&content_type=audio"
content_type=all or content_type=accessibility for most app text. OCR is fallback pixel text, not the main source of screen text on platforms where accessibility data is available.
when filtering by window, first inspect real stored window names from broad results. the visible title bar and stored window_name can differ.
avoid this while debugging:
curl "http://localhost:3030/search?limit=50&content_type=ocr&window_name=Exact%20Title"
curl "http://localhost:3030/search?limit=20&content_type=all"
window_name, app_name, start_time, or end_time only after you know the data exists.
notifications and external actions
if a pipe should play a sound, show a notification, send Telegram, update Notion, or call a webhook, split the debugging:
| layer | test |
|---|
| capture | does /search find the condition? |
| decision | does the prompt explain why it will or will not act? |
| integration | does the notification/API call work outside the pipe? |
| permissions | can the pipe call the endpoint or command? |
| schedule | does the pipe run manually before relying on cron? |
when to use chat, MCP, or pipes
| job | use |
|---|
| one question about recent activity | chat |
| external AI assistant needs screen memory | MCP |
| recurring workflow or scheduled output | pipe |
| structured integration with CRM/calendar/notes | pipe plus connections |
| local script or app integration | REST API |
collect a useful bug report
include:
- pipe name and
pipe.md
- schedule and whether manual run works
- output of
curl http://localhost:3030/health
- output of
curl http://localhost:3030/pipes/<name>/logs
- AI provider and model
- whether API auth is enabled
- OS and screenpipe version
related pages