Documentation

Everything you need to deploy Siftr safely in your Gmail workflow.

Getting StartedInstallationUsageFeaturesConfigurationTroubleshooting
01

Getting Started

Siftr is a local-first desktop app for high-volume Gmail cleanup. It combines clustering, AI-assisted suggestioning, and a mandatory human review queue before apply.

Before You Start

  • Use a Gmail account with cleanup permissions.
  • Prepare Google OAuth desktop client credentials (`client_secret.json`).
  • Confirm you understand the requested Gmail scopes: read, modify, and settings.basic.
  • Optional: configure local LLM runtime for richer suggestions (deterministic fallback is built in).
02

Installation

1

Download

Download the latest Siftr build from the download page.

2

Install or Extract

Run the installer or extract the portable package depending on your operating system.

3

Launch Siftr

Start the app and follow the first-run wizard to connect Gmail and configure runtime options.

Platform-Specific Install Guide

Detailed instructions for Windows, macOS, and Linux.

03

Usage

Step 1

Connect Gmail

Complete OAuth and verify account connection.

Step 2

Index and Cluster

Run scan to build grouped suggestions from mailbox patterns.

Step 3

Review Queue

Mark each suggestion Accepted or Rejected.

Step 4

Apply + Undo

Apply accepted actions and use undo/logs when needed.

04

Features

Manual Review Gate

No changes occur without explicit user confirmation.

Deterministic Fallback

Suggestion quality remains stable even when local LLM is unavailable.

Hybrid Preview Routing

Uses local cache first, then Gmail API fallback when needed.

Undo-Backed Apply

Session logs and idempotent handling reduce operational risk.

Local SQLite Storage

Fast local persistence with schema migration support.

Gmail Label Management

Create, rename, and remove labels in a controlled workflow.

05

Configuration

Siftr settings can be managed in the app settings screens and appsettings configuration.

Key settings
Google OAuth Secrets - desktop client credential file path
Gmail Request Limits - rate limits and retry behavior
Suggestion Label Prefix - naming convention for generated labels
Local LLM Runtime - model alias and model path
Storage Paths - local data and cache locations
06

Troubleshooting

OAuth setup fails

Verify desktop OAuth credentials exist at the configured path and that Gmail API is enabled in your Google Cloud project.

Suggestions look weak

Check whether local LLM runtime is available. Siftr falls back to deterministic grouping when LLM is missing.

Apply operation did not update expected mail

Inspect the session logs and query preview for scope mismatches or over-restrictive Gmail query filters.

App fails to start on Windows

Close running instances before rebuild/update and avoid launching from protected directories unless using installer mode.