ClipFlow

Productivity

Original Idea

Clipboard History Manager A Tauri desktop app that keeps a searchable history of everything you copy, with smart categorization and quick paste shortcuts.

Product Requirements Document (PRD): ClipFlow

1. Executive Summary

ClipFlow is a high-performance, local-first clipboard history manager built using the Tauri 2.9.x framework. It provides a persistent, searchable, and encrypted repository for everything a user copies (text, images, code, and HTML). By leveraging a minimalist overlay UI and smart "auto-paste" functionality, ClipFlow eliminates the productivity friction caused by the ephemeral nature of the system clipboard, allowing power users to recall and insert historical data in sub-10ms search times without leaving their active application.

2. Problem Statement

The standard system clipboard is a single-entry, volatile buffer. When a user copies a new item, the previous one is lost forever. This leads to:

  1. Data Loss: Accidental overwriting of critical snippets.
  2. Context Switching: Users must manually toggle between apps to find previously used information.
  3. Lack of Organization: No way to categorize, pin, or search through copy history.
  4. Security Risks: Sensitive data (passwords/CC numbers) remains in the clipboard history unless manually cleared.

3. Goals & Success Metrics

  • Performance: Achieve sub-10ms search responses for databases up to 100,000 items.
  • Efficiency: Maintain <1% CPU usage during background monitoring.
  • Adoption: Target 90% "Auto-paste" success rate across major applications (VS Code, Chrome, Slack).
  • Security: 100% encryption-at-rest for the local database.
  • UX: Overlay trigger-to-paste flow should take less than 2 seconds for a practiced user.

4. User Personas

4.1 The Polyglot Developer (Alex)

  • Needs: To copy multiple boilerplate snippets from documentation and paste them into different files.
  • Pain Point: Constantly switching between the browser and IDE.

4.2 The Content Curator (Sarah)

  • Needs: To collect quotes, URLs, and images for a research paper.
  • Pain Point: Losing a URL because she copied a paragraph of text immediately after.

4.3 The Data Analyst (Chen)

  • Needs: Moving specific data points between fragmented spreadsheets and a terminal.
  • Pain Point: The inability to "Stack" copies and paste them sequentially.

5. User Stories

  • As a Developer, I want ClipFlow to detect when I copy code so it can automatically apply syntax highlighting in the preview.
  • As a Privacy-conscious user, I want to blacklist 1Password so that my passwords are never saved in the history.
  • As a Power User, I want a global hotkey to show a minimalist search bar so I don't have to use my mouse.
  • As a Researcher, I want to "pin" specific project links so they aren't deleted by the 30-day auto-purge.

6. Functional Requirements

6.1 Clipboard Monitoring

  • Multi-format support: Capture UTF-8 text, Images (PNG/JPG), and HTML/Rich Text.
  • Metadata Capture: Store the source application name (via org.nspasteboard.source on macOS or GetClipboardOwner on Windows) and timestamp.
  • Duplicate Detection: Use SHA-256 hashing to prevent identical consecutive copies from cluttering the history.

6.2 Search & Discovery

  • Fuzzy Search: Implement trigram-based fuzzy matching for typo-tolerant filtering.
  • Smart Filters: Predetermined categories for "Images", "Links", "Code", and "Colors" (hex/rgb detection).
  • Source Filtering: Ability to filter history by the application it was copied from.

6.3 Interface & Interaction

  • Minimalist Overlay: A centered, "Spotlight-style" command palette.
  • Auto-Paste: Selecting an item (Enter key) hides the UI, focuses the previous window, and injects a Cmd+V / Ctrl+V command.
  • Pinning: Toggle "Pin" status to exclude items from the auto-deletion cleanup.

6.4 Security & Privacy

  • Blacklist: Ignore copies from specific PIDs or Application names (e.g., Bitwarden).
  • Privacy Mode: A "Pause" toggle to stop monitoring entirely.
  • Vault Encryption: Optional Argon2id-derived master key to encrypt the SQLite database.

7. Technical Requirements

7.1 Tech Stack

  • Framework: Tauri v2.9.x (Stable 2026).
  • Frontend: React 19, Tailwind CSS, Framer Motion v12.
  • Backend: Rust 1.80+.
  • Database: SQLite 3.45+ with FTS5 (Trigram tokenizer).
  • Persistence: SQLx v0.9.x (Async-first).

7.2 Platform Specifics (2026 Implementation)

  • macOS: Use Accessibility API for input injection; monitor changeCount via clipboard-master.
  • Windows: Use AddClipboardFormatListener (Win32) via clipboard-master; Azure Trusted Signing for CI/CD.
  • Linux: Implement libei and XDG Desktop Portal (Remote Desktop) for Wayland-compliant input injection.

8. Data Model

8.1 ClipboardItem

| Field | Type | Description | | :--- | :--- | :--- | | id | UUID | Primary Key | | content_payload | BLOB | The actual text or image data | | content_type | Enum | Text, Image, HTML, Link, Code | | source_app | String | Bundle ID or Executable name | | hash_digest | String | SHA-256 of content for deduplication | | is_pinned | Boolean | Prevents auto-purge | | created_at | Timestamp | ISO 8601 |

8.2 BlacklistRule

| Field | Type | Description | | :--- | :--- | :--- | | id | Integer | Primary Key | | pattern | String | App name or Regex | | is_active | Boolean | Toggle switch |

9. API Specification (Internal IPC)

invoke('search_history', { query: string })

  • Returns: Array<ClipboardItem>
  • Logic: Executes FTS5 MATCH query with trigram tokenizer.

invoke('paste_item', { id: string })

  • Action:
    1. Writes item to system clipboard.
    2. Minimizes ClipFlow.
    3. Calls Rust-native enigo or libei to trigger system-level paste.

10. UI/UX Requirements

  • Overlay: Must support transparent: true and visible: false on startup (Pre-warmed window pattern).
  • Animations: Use Framer Motion's layout prop for smooth list reordering when filtering.
  • Accessibility: Full keyboard navigation (Arrow keys to select, Cmd+Enter to copy without pasting).
  • Themes: Follow system preference (Dark/Light mode) automatically.

11. Non-Functional Requirements

  • Latency: The overlay must appear within 100ms of the hotkey press.
  • Reliability: Database integrity must survive hard reboots (using WAL mode).
  • Scalability: History should handle 50,000 items without UI lag using React 19's useTransition.

12. Out of Scope

  • Cloud Sync (v1 will be local-only).
  • Mobile version (Android/iOS).
  • OCR (Optical Character Recognition) for images.
  • Collaborative "Shared" clipboards.

13. Risks & Mitigations

  • Risk: OS updates breaking programmatic paste (especially macOS).
    • Mitigation: Implement a "Permission Onboarding" screen to guide users through Accessibility/Portal settings.
  • Risk: Large image blobs bloating the DB.
    • Mitigation: Store images as compressed files in the AppData directory and keep only file paths in SQLite.
  • Risk: CPU spikes during large searches.
    • Mitigation: Use SQLite LIMIT and OFFSET with async debouncing in React.

14. Implementation Tasks

Phase 1: Project Setup

  • [ ] Initialize Tauri 2.9.x project with alpha or stable 2026 releases.
  • [ ] Configure tauri.conf.json with multi-window support (hidden overlay).
  • [ ] Set up React 19 with Tailwind CSS and Framer Motion v12.
  • [ ] Initialize SQLx 0.9.x with SQLite and FTS5 extension.

Phase 2: Backend Monitoring

  • [ ] Implement clipboard-master trait for event-driven monitoring.
  • [ ] Build source application detection logic for macOS and Windows.
  • [ ] Create SHA-256 deduplication service in Rust.
  • [ ] Set up SQLite WAL mode and trigram tokenizer migrations.

Phase 3: The Overlay UI

  • [ ] Build "Spotlight-style" search bar with React 19 Activity component for background state.
  • [ ] Implement global hotkey listener (Cmd+Shift+V) in Rust.
  • [ ] Create fuzzy search IPC command with sub-10ms performance profiling.
  • [ ] Add Image preview component using Tauri’s convertFileSrc.

Phase 4: Programmatic Paste & Logic

  • [ ] Implement macOS Accessibility API integration for AXUIElement injection.
  • [ ] Build Windows SendInput logic for foreground window focus and paste.
  • [ ] Set up Linux libei / XDG Portal "Remote Desktop" session logic.
  • [ ] Implement "Smart Stacks" (nice-to-have) for multi-item selection.

Phase 5: Security & Distribution

  • [ ] Implement Argon2id key derivation for database encryption.
  • [ ] Integrate with system keychains (Keychain/Credential Manager) using keyring crate.
  • [ ] Create GitHub Actions workflow for Azure Trusted Signing (Windows) and Notarization (macOS).
  • [ ] Configure tauri-plugin-updater for automated signed updates.