Skip to main content

​
Overview

This guide will take you from zero to your first working screenpipe setup:
  1. Install screenpipe
  2. Start recording
  3. View your timeline
  4. Search your data
Total time: 5 minutes
This quickstart uses the desktop app. For CLI installation, see the Installation guide.

​
Step 1: Install screenpipe

1

Download the desktop app

Visit screenpi.pe/onboarding and download the installer for your platform:
  • macOS: .dmg installer (Apple Silicon and Intel)
  • Windows: .exe installer (Windows 10/11)
  • Linux: Build from source (see Installation)
2

Install and launch

  1. Open the downloaded .dmg file
  2. Drag screenpipe to your Applications folder
  3. Launch screenpipe from Applications
  4. If you see a security warning, go to System Settings > Privacy & Security and click “Open Anyway”
3

Grant permissions

screenpipe needs certain permissions to function:
  • Screen Recording: Required to capture your screen
  • Accessibility: Required to extract text from accessibility trees
  • Microphone (optional): For audio transcription
The app will guide you through granting these permissions on first launch.

​
Step 2: Start Recording

1

Configure capture settings

On first launch, you’ll see the settings screen:
  • Monitors: Select which monitors to capture (all selected by default)
  • Audio: Toggle microphone and system audio capture
  • Sensitivity: Choose Low, Medium (default), or High capture sensitivity
Low sensitivity uses less resources (ideal for laptops), while High sensitivity captures more frequently for maximum recall.
2

Start recording

Click the “Start Recording” button. screenpipe will begin capturing your screen and audio in the background.You’ll see a status indicator in your system tray (macOS menu bar or Windows taskbar):
  • Green dot: Recording active
  • Red dot: Recording paused or stopped
  • Yellow dot: Recording but with warnings
3

Let it record

Use your computer normally for a few minutes. screenpipe will:
  • Capture screenshots when you switch apps, click, type, or scroll
  • Extract text from your screen using accessibility APIs (with OCR fallback)
  • Transcribe any audio if you enabled audio capture
  • Store everything locally in ~/.screenpipe/ (macOS/Linux) or %APPDATA%\screenpipe\ (Windows)

​
Step 3: View Your Timeline

1

Open the timeline view

Click on the screenpipe icon in your system tray and select “Timeline” (or open the main app window).
2

Explore your activity

The timeline view shows:
  • Visual timeline: Scroll through screenshots of your activity
  • Timestamp: Exact time each capture was taken
  • App/Window: Which application and window was active
  • Trigger: What triggered the capture (app switch, click, typing pause, etc.)
Click any screenshot to see the full-resolution image and extracted text.
3

Filter by time range

Use the time range selector to jump to specific periods:
  • Last hour
  • Last 24 hours
  • Last 7 days
  • Custom date/time range

​
Step 4: Search Your Data

1

Open search

Click the search icon or press Cmd+K (macOS) / Ctrl+K (Windows) to open the search interface.
2

Try a natural language query

Type a search query in plain English:
# Search for text you saw
meeting notes about the budget

# Search audio transcriptions
what did John say about the database

# Search by application
slack messages about the project

# Search by time
emails I read this morning
screenpipe searches both visual text (OCR and accessibility) and audio transcriptions.
3

Review results

Search results show:
  • Screenshot thumbnail: Visual context of where the text appeared
  • Extracted text: The actual text found (highlighted)
  • Timestamp: When it was captured
  • App/Window: Which application it came from
Click any result to see the full screenshot and surrounding context.

​
Next Steps: Use the API

Now that screenpipe is recording, you can query your data programmatically: 
# Search for content from the last 5 minutes
curl "http://localhost:3030/search?q=meeting&content_type=all&limit=10"
The screenpipe API runs on localhost:3030 by default. See the API Reference for all available endpoints.

​
Example Use Cases

Now that you have screenpipe running, here are some things you can do:

AI Context

Give AI assistants (Claude, ChatGPT, Cursor) context about what you’re working on using the MCP server

Meeting Notes

Automatically transcribe and summarize meetings with the meeting-summary pipe

Time Tracking

Generate time breakdowns by app and project

Idea Tracker

Surface startup ideas from your browsing and market trends

​
Troubleshooting

  • Check that you’ve granted all required permissions (Screen Recording and Accessibility on macOS)
  • Look for error messages in the app or system tray icon
  • Try restarting the app
  • Make sure recording has been running for at least a few minutes
  • Check that the time range in your search includes the period when you were active
  • Try a broader search query
  • Lower the capture sensitivity in settings (Low uses ~5% CPU)
  • Disable audio transcription if you don’t need it
  • Exclude certain monitors from capture if you have 3+ displays
  • Make sure the screenpipe app is running
  • Check that port 3030 is not blocked by a firewall
  • Try accessing http://localhost:3030/health in your browser

​
Learn More

Installation

Detailed installation for all platforms

Architecture

How screenpipe works under the hood

API Reference

Complete API documentation

Pipes

Automate with AI agent plugins

MCP Server

Connect AI assistants to screenpipe

Join Discord

Get help from the community

Build docs developers (and LLMs) love

Get started for freeTalk to us