Build and manage scheduled tasks

The app calls these Scheduled tasks. The CLI command screenpipe pipe, local API paths under /pipes, and configuration file pipe.md retain their technical names. Use those exact identifiers in commands and configuration.

Looking for ready-to-use scheduled tasks? browse the task library →. If a scheduled task fails, use scheduled task debugging.

For a guided first setup, use reliable reports: define the source window, verify the saved output, and test a rerun before scheduling. See AI usage and controls for allowance, warnings, and stop versus auto-run behavior.

Browse and install community scheduled tasks

To find and install scheduled tasks others have made:

Open Scheduled tasks in Screenpipe
Click the Discover tab at the top
Browse featured and community scheduled tasks, or search for a specific one
Click GET to install any scheduled task
Open My tasks to run it, enable it, and configure the trigger

You can also browse all available scheduled tasks online at the online task library before installing.

Create a task in the app

Open Scheduled tasks → My tasks. If you already have tasks, click NEW to open the new scheduled task form. With an empty list, choose an example or describe the result you want. Review the generated prompt, output location, provider, and trigger before enabling automatic runs. A scheduled task can run on a time schedule, after a meeting, or when a supported event happens. You can also run it manually. Start with a manual test and verify the saved result before enabling its trigger.

Build a task with a coding assistant

Copy this prompt into Claude Code, cursor, or any AI coding assistant:

create a screenpipe scheduled task that [DESCRIBE WHAT YOU WANT].

## what is screenpipe?

screenpipe is a desktop app that captures your screen text primarily through accessibility APIs, falls back to OCR when needed, and records audio transcriptions.
it runs a local API at http://localhost:3030 that lets you query everything you've seen, said, or heard.

## what is a scheduled task?

a scheduled task 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 scheduled task'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 -H "Authorization: Bearer $SCREENPIPE_LOCAL_API_KEY" \
  "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: returned URL metadata; it is not a `/search` filter. To find pages by URL text, use `q` (for example, `q=github.com`) and inspect each result's `browser_url`.
- min_length / max_length: filter by text length
- speaker_ids: filter audio by speaker IDs

### screen text results (what was on screen)
each result contains:
- text: extracted accessibility text or OCR fallback 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 -H "Authorization: Bearer $SCREENPIPE_LOCAL_API_KEY" "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

## local API authentication and secrets

screenpipe injects `SCREENPIPE_LOCAL_API_KEY` into scheduled task runs. add `-H "Authorization: Bearer $SCREENPIPE_LOCAL_API_KEY"` to every protected local API request.

store keys for external services 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 **Scheduled tasks → My tasks** to enable, run, and view logs. browse and install scheduled tasks from the **Discover** tab.

or use the REST API:
install: curl -X POST http://localhost:3030/pipes/install -H "Authorization: Bearer $SCREENPIPE_LOCAL_API_KEY" -H "Content-Type: application/json" -d '{"source": "~/.screenpipe/pipes/my-pipe"}'
enable:  curl -X POST http://localhost:3030/pipes/my-pipe/enable -H "Authorization: Bearer $SCREENPIPE_LOCAL_API_KEY" -H "Content-Type: application/json" -d '{"enabled": true}'
test:    curl -X POST http://localhost:3030/pipes/my-pipe/run -H "Authorization: Bearer $SCREENPIPE_LOCAL_API_KEY"
logs:    curl http://localhost:3030/pipes/my-pipe/logs -H "Authorization: Bearer $SCREENPIPE_LOCAL_API_KEY"

Replace [DESCRIBE WHAT YOU WANT] with your use case — e.g. “tracks my time in Toggl based on what apps I’m using”, “writes daily summaries to Obsidian”, “sends me a Slack message if I’ve been on twitter for more than 30 minutes”.

What are scheduled tasks?

Scheduled tasks are automated workflows that run on your Screenpipe data at regular intervals. Each scheduled task is a markdown file with a prompt and a schedule. Under the hood, Screenpipe runs a coding agent (like pi) that can query your screen data, call APIs, write files, and take actions.

Use chat, MCP, or a scheduled task?

Job	Use
Ask one question about recent activity	Chat
Give Claude, Codex, Cursor, or another assistant screen memory	MCP
Run the same workflow every day or hour	Scheduled task
Write to Obsidian, CRM, Slack, or another app	Scheduled task plus connections
Build an app or script against Screenpipe	API recipes

A scheduled task is just one file: pipe.md

~/.screenpipe/pipes/
├── daily-journal/
│   └── pipe.md
├── toggl-sync/
│   ├── pipe.md
│   └── .env          # secrets (api keys)
└── obsidian-sync/
    └── pipe.md

Creating a scheduled task

Create a folder in ~/.screenpipe/pipes/ with a pipe.md file:

mkdir -p ~/.screenpipe/pipes/my-pipe
cat > ~/.screenpipe/pipes/my-pipe/pipe.md << 'EOF'
---
schedule: every 30m
enabled: true
---

Summarize my screen activity for the last 30 minutes.
Query screenpipe at http://localhost:3030/search using the time range from the context header.
Authenticate with the SCREENPIPE_LOCAL_API_KEY environment variable.
Write the summary to ./output/<date>.md
EOF

# install + enable + test it from the CLI (no install needed — npx / bunx / bun x all work):
npx -y screenpipe@latest pipe install ~/.screenpipe/pipes/my-pipe
npx -y screenpipe@latest pipe enable my-pipe
npx -y screenpipe@latest pipe run my-pipe        # run once now to test
#
# (or use the desktop app: Scheduled tasks → My tasks — or the authenticated REST API)

Manage scheduled tasks from the CLI

Every scheduled task action is available from the CLI — no separate install. npx -y screenpipe@latest, bunx screenpipe@latest, and bun x screenpipe@latest are equivalent; use whichever the machine has.

npx -y screenpipe@latest pipe list                   # list all scheduled tasks
npx -y screenpipe@latest pipe install <url-or-path>  # install from a GitHub URL or a local folder
npx -y screenpipe@latest pipe enable <name>          # turn the schedule on
npx -y screenpipe@latest pipe disable <name>         # turn it off
npx -y screenpipe@latest pipe run <name>             # run once now (test before the schedule fires)
npx -y screenpipe@latest pipe logs <name>            # view execution logs
npx -y screenpipe@latest pipe delete <name>          # remove a scheduled task

Run CLI commands from a clean temp directory to avoid node_modules conflicts: cd "$(mktemp -d)" && npx -y screenpipe@latest pipe list.

This is how you turn a one-off into a recurring cron automation: write a pipe.md with a schedule (e.g. 0 9 * * *), install then enable it, and Screenpipe runs it on that cron. You can also hand these commands to any AI agent — e.g. “create a Screenpipe scheduled task that summarizes my day at 6pm” — and let it scaffold, install, and enable the scheduled task for you.

Pipe.md format

Every pipe.md starts with YAML frontmatter between --- markers, followed by the prompt:

---
schedule: every 2h
enabled: true
---

Your prompt goes here. This is what the AI agent will execute.
You can reference screenpipe's API, write files, call external APIs, etc.

Frontmatter fields

Field	Required	Default	Description
`schedule`	Yes	`manual`	`every 30m`, `every 2h`, `daily`, cron (`0 /2 * *`), or `manual`
`enabled`	No	`true`	Whether the scheduler runs this scheduled task
`timeout`	No	`300` (5 min)	Execution timeout in seconds. Increase for slow models (e.g., `timeout: 2400` for 40 min). If a scheduled task runs over this limit, it is terminated.

Context header

Before execution, Screenpipe prepends a context header to the prompt:

Default run lookback: 2026-02-12T13:00:00Z to 2026-02-12T14:00:00Z
Structured output targets may declare an authoritative time range that overrides this default for that target.
Run date: 2026-02-12
Timezone: PST (UTC-08:00)
Pipe name: my-pipe

The agent uses this context to identify the run. Define the intended report window and output destination in the task instructions; an output target may override the default lookback. Use the injected local API URL and token for requests.

Schedule formats

Format	Example	Description
Interval	`every 30m`, `every 2h`	Runs at fixed intervals
Daily	`daily`	Runs once per day
Cron	`0 /2 * *`	Standard 5-field cron expression
Manual	`manual`	Only runs when triggered manually

Example: scheduled task with longer timeout for slow models

If your scheduled task uses a slower AI model or runs complex analysis, increase the timeout:

---
schedule: daily
enabled: true
timeout: 2400
---

Analyze user activity and generate a detailed report.
Use claude-opus or other capable models for thorough analysis.
Write results to ./output/daily-report.md

In this example, the scheduled task will run daily and has up to 40 minutes to complete. Without the timeout field, it would be limited to 5 minutes and likely timeout on slower models.

Manage scheduled tasks

Use the desktop app (Scheduled tasks → My tasks) or the REST API:

HTTP API

When Screenpipe is running, scheduled tasks are also manageable via the local API:

export SCREENPIPE_LOCAL_API_KEY="$(npx -y screenpipe@latest auth token)"

# list all scheduled tasks
curl http://localhost:3030/pipes \
  -H "Authorization: Bearer $SCREENPIPE_LOCAL_API_KEY"

# run a scheduled task
curl -X POST http://localhost:3030/pipes/my-pipe/run \
  -H "Authorization: Bearer $SCREENPIPE_LOCAL_API_KEY"

# enable/disable
curl -X POST http://localhost:3030/pipes/my-pipe/enable \
  -H "Authorization: Bearer $SCREENPIPE_LOCAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

# update scheduled task content
curl -X POST http://localhost:3030/pipes/my-pipe/config \
  -H "Authorization: Bearer $SCREENPIPE_LOCAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"raw_content": "---\nschedule: every 1h\nenabled: true\n---\n\nYour prompt here..."}'

# view logs
curl http://localhost:3030/pipes/my-pipe/logs \
  -H "Authorization: Bearer $SCREENPIPE_LOCAL_API_KEY"

# install from URL
curl -X POST http://localhost:3030/pipes/install \
  -H "Authorization: Bearer $SCREENPIPE_LOCAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": "https://example.com/pipe.md"}'

App ui

Go to Scheduled tasks → My tasks to see installed scheduled tasks, toggle schedules, run them manually, select an AI preset, and view logs.

Examples

Reviewed project time report

---
schedule: manual
enabled: false
---

Create a draft project time report for the time range in the context header.

1. Authenticate local API requests with SCREENPIPE_LOCAL_API_KEY
2. Use /activity-summary for numeric active-time totals
3. Use bounded /search results to suggest project labels and describe work
4. Put ambiguous blocks in a needs-review section
5. Write the draft to ./output/project-time-report.md
6. Do not send it, create an invoice, or update an external time tracker

See consultant time tracking for the full workflow.

Daily journal (Obsidian)

---
schedule: every 2h
enabled: true
---

Summarize my screen activity into a daily journal entry.
Query screenpipe search API for the time range in the context header.
Write to ~/obsidian-vault/screenpipe/<date>.md
Use [[wiki-links]] for people and projects.
Include timeline deep links: [time](screenpipe://timeline?timestamp=<ISO8601>)

Standup report

---
schedule: daily
enabled: true
---

Generate a standup report from yesterday's screen activity.
Format: what I did, what I'm doing, blockers.
Write to ./output/<date>.md

AI presets

In the Screenpipe app, go to Settings → AI settings to configure presets (model + provider combinations). In Scheduled tasks → My tasks, you can assign a preset to each scheduled task — this overrides the model/provider in the frontmatter. Screenpipe auto-creates a default preset using Screenpipe cloud.

AI providers

By default, scheduled tasks use Screenpipe cloud — no setup needed if you have a Screenpipe account. To use your own AI subscription (Claude Pro, ChatGPT Plus, Gemini, or API keys), scheduled tasks reuse pi’s native auth system:

Option 1: subscription (free with existing plan)

# run pi interactively and use /login
pi
# then type: /login
# select Claude Pro, ChatGPT Plus, GitHub Copilot, or Google Gemini

Option 2: API key

Add to ~/.pi/agent/auth.json:

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "google": { "type": "api_key", "key": "..." }
}

Or set environment variables: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY.

Using in a scheduled task

Add provider to your pipe.md frontmatter:

---
schedule: every 30m
provider: anthropic
model: claude-haiku-4-5@20251001
---

Provider resolution: preset (if set) → frontmatter provider/model → Screenpipe cloud.

Secrets

Store API keys in .env files inside the scheduled task folder:

echo "TOGGL_API_KEY=your_key_here" > ~/.screenpipe/pipes/toggl-sync/.env

The scheduled task prompt can reference them: source .env && curl -u $TOGGL_API_KEY:api_token ... Never put secrets in pipe.md — the prompt may be visible in logs.

Architecture

pipe.md (prompt + config)
  → task scheduler (parses frontmatter, schedules runs)
    → agent executor (pi, claude-code, etc.)
      → agent queries screenpipe API + executes actions
        → output saved to task folder

Agent ≠ model: the agent is the CLI tool (pi, claude-code). The model is the LLM (haiku, opus, llama).
Time-scheduled runs are serialized; event-triggered runs use a separate bounded queue
Default lookback uses a parsed interval, capped at 8 hours, or one hour when no interval is parsed. An output target can supply its own authoritative range
Logs saved to ~/.screenpipe/pipes/{name}/logs/ as JSON

Troubleshooting

For a production-style debugging flow, including logs, stuck runs, provider auth, connection proxies, and permissions, see debug Screenpipe scheduled tasks.

Scheduled task scheduled but doesn’t run

Problem: Windows task scheduler or cron shows the task running, but the scheduled task produces no output. Solution: the scheduled task agent needs to know which scheduled task it’s executing. The context header includes Pipe name: <name> so the agent can identify itself. Make sure:

The scheduled task folder name matches the expected scheduled task name (e.g., ~/.screenpipe/pipes/my-pipe/)
The scheduled task is listed in npx -y screenpipe@latest pipe list
Check logs: npx -y screenpipe@latest pipe logs my-pipe

Scheduled task runs but produces empty output

Problem: scheduled task executes successfully but generates no files or notifications. Solution: ensure your scheduled task prompt includes concrete instructions to:

Query Screenpipe API with the injected local token and a bounded start time
Write output files (e.g., to ./output/<date>.md)
Or send notifications (e.g., POST http://localhost:11435/notify)

Test locally first: npx -y screenpipe@latest pipe run my-pipe to see logs before relying on scheduled execution.

Windows task scheduler permission denied

Problem: Windows task scheduler fails with permission errors when running scheduled tasks. Solution: ensure Screenpipe engine is running before the task executes. Scheduled tasks require the local API at http://localhost:3030. Schedule the scheduled task after the app starts, or use the desktop UI instead.

Security & permissions

By default, scheduled tasks have full API access — they can call any Screenpipe endpoint. This is fine for scheduled tasks you write yourself, but if a scheduled task doesn’t need write access, you can restrict it. Add permissions to your frontmatter:

---
schedule: every 30m
permissions: reader
---

Presets

Preset	What it allows
(none)	Full access — no restrictions, same as always
`reader`	Restricted API access: `/search`, `/activity-summary`, `/meetings` (GET), `/notify`, `/health`
`writer`	Reader + meeting writes, memory writes
`admin`	Everything (explicit opt-in, useful for logging)

Custom rules

Use typed patterns for fine-grained control over endpoints and data:

---
schedule: every 1h
permissions:
  allow:
    - App(Slack, Chrome)
    - Content(accessibility, audio)
  deny:
    - Api(* /meetings/stop)
    - App(1Password)
    - Window(*incognito*)
---

Rule types: Api(METHOD /path), App(name), Window(glob), Content(type). Deny always wins.

If your scheduled task doesn’t need to write data, review permissions: reader to restrict supported Screenpipe API calls, including destructive operations. This does not sandbox other agent tools.

Protecting API keys & credentials

If you worry that an agent could access API keys or passwords visible on screen, use .env files (never put secrets in pipe.md itself):

# keep secrets out of the prompt; authorized processes can still read this file
echo "GITHUB_TOKEN=ghp_..." > ~/.screenpipe/pipes/my-pipe/.env
echo "SLACK_API_KEY=xoxb-..." >> ~/.screenpipe/pipes/my-pipe/.env

Then reference them in your scheduled task prompt:

source .env && curl -H "Authorization: Bearer $GITHUB_TOKEN" https://api.github.com/...

Keep secrets out of the prompt and avoid printing them in terminal output or logs. A .env file is still readable by processes with filesystem access, including an agent authorized to run shell commands. Review file access and any external actions separately. The permissions: reader preset limits supported Screenpipe API requests. It is not a filesystem or network sandbox, and it does not prevent an agent from using other available tools. Review the allowed endpoints and the agent runtime before running a task. See the full reference: scheduled task permissions →

Built-in Home shortcuts

Screenpipe currently ships four Home shortcuts. These are available without a Store install; community and integration scheduled tasks remain under Scheduled tasks → Discover.

Scheduled task	What it does	Schedule
Automate My Work	Find a repeated workflow and propose a testable automation	on-demand
Day Recap	Summarize accomplishments, key moments, and unfinished work	on-demand
Time Breakdown	Review app, project, and category activity	on-demand
Missed To-Dos	Find likely unresolved commitments from recent work	on-demand

Need help building scheduled tasks? join our Discord — share your scheduled tasks, get feedback, and see what others are building. Download Screenpipe →

​Browse and install community scheduled tasks

​Create a task in the app

​Build a task with a coding assistant

​What are scheduled tasks?

​Use chat, MCP, or a scheduled task?

​Creating a scheduled task

​Manage scheduled tasks from the CLI

​Pipe.md format

​Frontmatter fields

​Context header

​Schedule formats

​Example: scheduled task with longer timeout for slow models

​Manage scheduled tasks

​HTTP API

​App ui

​Examples

​Reviewed project time report

​Daily journal (Obsidian)

​Standup report

​AI presets

​AI providers

​Option 1: subscription (free with existing plan)

​Option 2: API key

​Using in a scheduled task

​Secrets

​Architecture

​Troubleshooting

​Scheduled task scheduled but doesn’t run

​Scheduled task runs but produces empty output

​Windows task scheduler permission denied

​Security & permissions

​Presets

​Custom rules

​Protecting API keys & credentials

​Built-in Home shortcuts

Browse and install community scheduled tasks

Create a task in the app

Build a task with a coding assistant

What are scheduled tasks?

Use chat, MCP, or a scheduled task?

Creating a scheduled task

Manage scheduled tasks from the CLI

Pipe.md format

Frontmatter fields

Context header

Schedule formats

Example: scheduled task with longer timeout for slow models

Manage scheduled tasks

HTTP API

App ui

Examples

Reviewed project time report

Daily journal (Obsidian)

Standup report

AI presets

AI providers

Option 1: subscription (free with existing plan)

Option 2: API key

Using in a scheduled task

Secrets

Architecture

Troubleshooting

Scheduled task scheduled but doesn’t run

Scheduled task runs but produces empty output

Windows task scheduler permission denied

Security & permissions

Presets

Custom rules

Protecting API keys & credentials

Built-in Home shortcuts