Screenpipe Development Assistant

Expert assistant for the screenpipe project - an AI system that records, searches, and automates everything on your computer. All local, all private, all yours.

Project Overview

Screenpipe turns your computer into a personal AI that knows everything you've done. It continuously records screen content and audio, makes it searchable, and enables automation - all running locally on your machine.

Tech Stack & Tools

Package Managers

Key Technologies

Project Structure

Understand the codebase organization:

1. **`screenpipe-app-tauri/`** - Desktop application

- Tauri-based native wrapper

- Next.js frontend

- Entry point for user interface

2. **`screenpipe-server/`** - Core backend services

- Rust-based server

- Data storage and retrieval

- API endpoints

3. **`screenpipe-audio/`** - Audio capture module

- Audio recording

- Speech-to-text transcription

- Audio processing pipelines

4. **`screenpipe-vision/`** - Screen capture module

- Screen recording

- OCR (Optical Character Recognition)

- Visual content extraction

Development Guidelines

When Working with Code

1. **Use the correct package manager**:

- For JavaScript/TypeScript files: `bun install`, `bun run`, `bun test`

- For Rust files: `cargo build`, `cargo test`, `cargo run`

2. **Testing**:

- Run Rust tests: `cargo test`

- Run JavaScript/TypeScript tests: `bun test`

3. **Configuration Files**:

- Tauri config: `screenpipe-app-tauri/src-tauri/tauri.conf.json`

- Environment variables: `.env.local` (gitignored, must be created locally)

Analytics Configuration

PostHog analytics is integrated:

When working with analytics code, reference these values from environment variables.

macOS Development Notes

**Code Signing for Development Builds**:

Deprecated Features

Do **NOT** mention or implement:

These features have been removed from the project and should not be referenced in code or documentation.

Common Development Tasks

Setting Up Environment

1. Clone the repository

2. Create `.env.local` in the root with required environment variables (PostHog API key, etc.)

3. Install dependencies:

- Root and JS/TS projects: `bun install`

- Rust projects will install on first build

Building the Project

1. **Desktop App**:

```bash

cd screenpipe-app-tauri

bun install

bun run tauri dev

```

2. **Rust Backend**:

```bash

cd screenpipe-server

cargo build

```

Running Tests

1. **All Rust tests**:

```bash

cargo test

```

2. **JavaScript/TypeScript tests**:

```bash

bun test

```

Code Quality Guidelines

1. **Follow existing patterns**: Before implementing new features, explore similar functionality in the codebase

2. **Prioritize privacy**: All data processing should happen locally

3. **Performance matters**: This is a continuously-running recording system

4. **Cross-platform compatibility**: Consider macOS, Windows, and Linux

5. **Type safety**: Use TypeScript types and Rust's type system fully

Troubleshooting Common Issues

Permission Issues on macOS

Build Failures

Audio/Vision Module Issues

Best Practices

1. **Before making changes**: Read existing code in the relevant directory

2. **Use appropriate tools**: Bun for JS/TS, Cargo for Rust - never mix

3. **Test locally**: Run tests before committing

4. **Respect privacy**: Never send data externally without explicit user consent

5. **Document complex logic**: This is a sophisticated system - clear comments help

6. **Check platform requirements**: Different features have different OS requirements

Getting Help

When you need clarification: