create a screenpipe pipe that [DESCRIBE WHAT YOU WANT].
## what is screenpipe?
screenpipe is a desktop app that continuously records your screen (OCR) and audio (transcription).
it runs a local API at http://localhost:3030 that lets you query everything you've seen, said, or heard.
## what is a pipe?
a pipe is a scheduled AI agent defined as a single markdown file: ~/.screenpipe/pipes/{name}/pipe.md
every N minutes, screenpipe runs a coding agent (like pi or claude-code) with the pipe's prompt.
the agent can query your screen data, write files, call external APIs, send notifications, etc.
## pipe.md format
the file starts with YAML frontmatter, then the prompt body:
---
schedule: every 30m
enabled: true
---
Your prompt instructions here...
## context header
before execution, screenpipe prepends a context header to the prompt with:
- time range (start/end timestamps based on the schedule interval)
- current date
- user's timezone
- screenpipe API base URL
- output directory
the AI agent uses this context to query the right time range. no template variables needed in the prompt.
## screenpipe search API
the agent queries screen data via the local REST API:
curl "http://localhost:3030/search?limit=20&content_type=all&start_time=<ISO8601>&end_time=<ISO8601>"
### query parameters
- q: text search query (optional)
- content_type: "all" | "ocr" | "audio" | "input" | "accessibility"
- limit: max results (default 20)
- offset: pagination offset
- start_time / end_time: ISO 8601 timestamps
- app_name: filter by app (e.g. "chrome", "cursor")
- window_name: filter by window title
- browser_url: filter by URL (e.g. "github.com")
- min_length / max_length: filter by text length
- speaker_ids: filter audio by speaker IDs
### vision results (what was on screen)
each result contains:
- text: the extracted text visible on screen
- app_name: which app was active (e.g. "Arc", "Cursor", "Slack")
- window_name: the window title
- browser_url: the URL if it was a browser
- timestamp: when it was captured
- file_path: path to the video frame
- focused: whether the window was focused
### audio results (what was said/heard)
each result contains:
- transcription: the spoken text
- speaker_id: numeric speaker identifier
- timestamp: when it was captured
- device_name: which audio device (mic or system audio)
- device_type: "input" (microphone) or "output" (system audio)
### accessibility results (accessibility tree text)
each result contains:
- text: text from the accessibility tree
- app_name: which app was active
- window_name: the window title
- timestamp: when it was captured
### input results (user actions)
query via: curl "http://localhost:3030/search?content_type=input&app_name=Slack&limit=50&start_time=<ISO8601>&end_time=<ISO8601>"
event types: text (keyboard input), click, app_switch, window_focus, clipboard, scroll
## secrets
store API keys in a .env file next to pipe.md (never in the prompt itself):
echo "API_KEY=your_key" > ~/.screenpipe/pipes/my-pipe/.env
reference in prompt: source .env && curl -H "Authorization: Bearer $API_KEY" ...
## after creating the file
use the desktop app: go to **settings → pipes** to install, enable, run, and view logs.
or use the REST API:
install: curl -X POST http://localhost:3030/pipes/install -H "Content-Type: application/json" -d '{"source": "~/.screenpipe/pipes/my-pipe"}'
enable: curl -X POST http://localhost:3030/pipes/my-pipe/enable -H "Content-Type: application/json" -d '{"enabled": true}'
test: curl -X POST http://localhost:3030/pipes/my-pipe/run
logs: curl http://localhost:3030/pipes/my-pipe/logs