🧠 BuffBrain

The clipboard manager with a brain.
On-device semantic search. AI-powered classification. Blazingly fast native performance.

Semantic search finds what you meant, not just what you typed. All AI runs offline on your machine — zero data leaves your Mac.

Features • Semantic Search • vs Competition • Architecture • Build

---

---

✦ Features

Capability	BuffBrain
Semantic Search	✅ On-device MiniLM-L6 (~22MB), 384-dim vectors, cosine similarity ranking
Text Classification	✅ 30+ heuristics: code (JS/Python/Rust/Go/SQL/etc), links (URLs/email/IPs), plain text
OpenRouter AI Tagger	✅ Optional Llama 3.1 8B via API key — refines classification + auto-detect
Image Clipboard Support	✅ Thumbnail previews stored in SQLite
Pin / Favorites	✅ Toggle pin per clip, sorted to top
Global Shortcut	✅ Cmd+Shift+V toggles window anywhere
Tray Icon	✅ Menu bar icon with Show/Hide/Quit + click toggle
Auto-start	✅ Launch at login (configurable)
System Tray Toggle	✅ Show/hide tray icon from Settings
Frameless Glass UI	✅ Transparent, always-on-top, blur backdrop, 720×460
Auto-hide on blur	✅ Window disappears when focus is lost
Secure API Key Storage	✅ macOS Keychain via keyring v3
Dark/Light/System Theme	✅ Three-way toggle
Adjustable Max Clips	✅ Configurable history limit
No Telemetry	✅ Zero analytics, zero external calls (unless you opt into OpenRouter)

---

✦ Semantic Search

BuffBrain embeds every clip into a 384-dimensional vector using a quantized MiniLM-L6-v2 ONNX model running locally via ort (ONNX Runtime).

How it works:

Clip text → Tokenizer (WordPiece) → MiniLM-L6 ONNX → Mean pooling → L2 normalize → 384-dim vector

• Model: sentence-transformers/all-MiniLM-L6-v2 — quantized to ~22MB
• Runtime: ort (ONNX Runtime) — no Python, no PyTorch, no GPU required
• Search: Cosine similarity over all stored embeddings, ranked + sorted by relevance
• Speed: Sub-10ms inference per clip on Apple Silicon (M-series)

Toggle between Lexical (🔍) and Semantic (✨) search modes in the search bar:

Mode	Behavior
🔍 Lexical	Classic text match — finds what you typed
✨ Semantic	AI meaning match — finds what you meant

Example: searching "fruit" finds "apple", "banana", "orange" clips even though none contain the word "fruit."

---

✦ On-Device AI, No Compromises

No cloud dependency. No API key required. No data leaves your Mac.

┌─────────────────────────────────────────────────────────────────┐
│  BuffBrain                                                        │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │  ONNX Runtime (ort)                                    │     │
│  │  ┌──────────────────────────────────────────────────┐  │     │
│  │  │  MiniLM-L6-v2 (quantized, 22MB)                  │  │     │
│  │  │  • Tokenizer → Embed → Normalize → Store          │  │     │
│  │  └──────────────────────────────────────────────────┘  │     │
│  │  ┌──────────────────────────────────────────────────┐  │     │
│  │  │  Heuristic Classifier (30+ rules)                 │  │     │
│  │  │  • Code detection: JS/TS, Python, Rust, Go, SQL   │  │     │
│  │  │    HTML/XML, CSS, JSON, YAML, TOML, Makefiles     │  │     │
│  │  │    Shell scripts, stack traces, git diffs, etc.   │  │     │
│  │  │  • Link detection: URLs, email, IPs, file paths   │  │     │
│  │  └──────────────────────────────────────────────────┘  │     │
│  │  ┌──────────────────────────────────────────────────┐  │     │
│  │  │  OpenRouter AI (optional) — Llama 3.1 8B         │  │     │
│  │  │  • Refines classification via API                │  │     │
│  │  │  • Only enabled if user provides API key          │  │     │
│  │  └──────────────────────────────────────────────────┘  │     │
│  └─────────────────────────────────────────────────────────┘     │
│  Storage: SQLite + macOS Keychain                                 │
└─────────────────────────────────────────────────────────────────┘

---

✦ vs The Competition

| Feature | BuffBrain 🧠 | Alfred | Raycast | Maccy | Ditto | PastePilot | |---|---|---|---|---|---|---|---| | Semantic search | ✅ On-device MiniLM-L6 | ❌ | ❌ | ❌ | ❌ | ❌ | | AI classification | ✅ Heuristic 30+ rules + optional LLM | ❌ | ❌ | ❌ | ❌ | ✅ GPT-powered | | Local AI only | ✅ Zero cloud (by default) | ❌ | ❌ | ❌ | ❌ | ❌ Cloud-only | | Free & open source | ✅ MIT | ❌ £49+ | ❌ Freemium | ✅ Free | ✅ Free | ⚠️ Freemium | | Cross-platform | ✅ macOS, Linux, Windows | ✅ Mac | ✅ Mac | ✅ Mac | ✅ Windows | ✅ Mac | | Image clips | ✅ Thumbnails in SQLite | ❌ Premium only | ✅ | ❌ | ✅ | ✅ | | Global shortcut | ✅ Cmd+Shift+V | ✅ | ✅ | ✅ | ✅ | ✅ | | Frameless UI | ✅ Glass, always-on-top | ❌ | ❌ | ❌ | ❌ | ❌ | | Clipboard types (code/link/text) | ✅ Auto-detected | ✅ Tags | ✅ Tags | ❌ | ❌ | ❌ | | Auto-start | ✅ Configurable | ✅ | ✅ | ✅ | ✅ | ✅ | | macOS Keychain | ✅ API keys secured | ❌ | ❌ | ❌ | ❌ | ❌ | | Privacy | ✅ No telemetry | ⚠️ Some | ⚠️ Some | ✅ Clean | ✅ Clean | ⚠️ Some | | Platform | macOS, Linux, Windows | macOS | macOS | macOS | Windows | macOS |

Key differentiators:

• Only clipboard manager with on-device semantic search — no competitor offers meaning-based retrieval
• True privacy — heuristics + bundled ONNX model mean zero external calls unless you add an API key
• Free and open source — MIT license, no paid tiers, no data mining
• Modern tech stack — Rust backend, React 19 + TypeScript frontend, Tauri 2 framework

---

✦ Architecture

┌─────────────────────────────────────┐
│  Frontend (React 19 + TypeScript)    │
│  ┌───────────┐ ┌──────────────────┐ │
│  │ SearchBar │ │   Settings       │ │
│  │ • Lexical │ │ • Theme toggle   │ │
│  │ • Semantic│ │ • AI on/off      │ │
│  │ • Tabs    │ │ • Tray toggle    │ │
│  └─────┬─────┘ │ • Auto-start     │ │
│        │       │ • API key mgmt   │ │
│  ┌─────▼─────┐ └──────────────────┘ │
│  │  ClipList  │  ┌───────────────┐  │
│  │  • Cards   │  │   Icons       │  │
│  │  • Preview │  │   (SVG React) │  │
│  │  • Pin/Delete               │  │  │
│  └─────┬─────┘  └───────────────┘  │
│        │ IPC (invoke / events)      │
├────────┼────────────────────────────┤
│  Backend (Rust + Tauri 2)           │
│  ┌──────▼──────┐ ┌──────────────┐  │
│  │  commands   │ │  clipboard   │  │
│  │  • CRUD     │ │  • Polling   │  │
│  │  • Search   │ │  • Auto-type │  │
│  │  • Config   │ │  • Watcher   │  │
│  └──────┬──────┘ └──────┬───────┘  │
│         │               │           │
│  ┌──────▼───────────────▼───────┐  │
│  │         db (SQLite)           │  │
│  │  • clips (content, type,      │  │
│  │    source, embedding, pinned) │  │
│  │  • config (key-value store)   │  │
│  └──────────────┬───────────────┘  │
│                 │                   │
│  ┌──────────────▼───────────────┐  │
│  │    embed (ONNX Runtime)       │  │
│  │  • MiniLM-L6-v2 quantized     │  │
│  │  • tokenizer → inference →    │  │
│  │    mean-pool → normalize      │  │
│  └──────────────────────────────┘  │
│                                     │
│  Storage:                           │
│  • SQLite: ~/Library/Application    │
│    Support/com.buffbrain.app/       │
│  • Keychain: OpenAI/OpenRouter key  │
└─────────────────────────────────────┘

Tech Stack

Layer	Technology
Desktop Framework	Tauri 2 (Rust + WebView)
Frontend	React 19, TypeScript, Vite 7
Backend	Rust with tokio, serde, anyhow
Storage	rusqlite (bundled SQLite) with WAL mode
AI Runtime	ort (ONNX Runtime) v2.0.0-rc.12
AI Model	MiniLM-L6-v2 quantized (~22MB)
Tokenization	tokenizers (Rust), WordPiece
Secrets	keyring v3 (macOS Keychain)
Clipboard	tauri-plugin-clipboard-manager v2
Shortcuts	tauri-plugin-global-shortcut v2
Auto-start	tauri-plugin-autostart v2
Window	Frameless, transparent, macos-private-api

---

✦ Install

Download the latest release for your platform from the Releases page.

macOS — Gatekeeper workaround

v0.1.x builds are ad-hoc signed (no Apple Developer ID), so macOS will block the first launch with one of:

• "BuffBrain.app is damaged and can't be opened"
• "BuffBrain.app cannot be opened because the developer cannot be verified"

Pick one of these to bypass:

Option A — GUI (one-time):

1. Open the .dmg and drag BuffBrain to /Applications
2. In /Applications, right-click BuffBrain.app → Open (not double-click)
3. Click Open in the warning dialog
4. After that, double-click works normally

Option B — Terminal (works on Apple Silicon too):

xattr -d com.apple.quarantine "/Applications/BuffBrain.app"

Option C — ad-hoc sign manually (if the above still fails):

codesign --force --deep --sign - "/Applications/BuffBrain.app"

Proper Developer ID signing + notarization is on the roadmap — until then, please use one of the workarounds above. See issue tracker for status.

Linux

sudo dpkg -i BuffBrain_*.deb
sudo apt-get install -f   # resolve any missing deps
buffbrain

Windows

Run the NSIS installer .exe. SmartScreen may show a warning for unsigned binaries — click More info → Run anyway.

---

✦ Build from Source

Prerequisites

• Rust (latest stable)
• Node.js 18+

Platform-specific:

• macOS: Xcode Command Line Tools (xcode-select --install)
• Linux: sudo apt install libwebkit2gtk-4.1-dev librsvg2-dev patchelf libssl-dev libgtk-3-dev
• Windows: NSIS (for .exe installer)

Quick Start

git clone https://github.com/your-username/buffbrain.git
cd buffbrain

# Install JS dependencies
npm install

# Development mode (hot-reload)
npm run tauri dev

# Or use the dev script
./scripts/dev.sh

Production Build

npm run tauri build

Output by platform:

Platform	Bundle
macOS (Apple Silicon)	bundle/dmg/BuffBrain_0.1.1_aarch64.dmg
macOS (Intel)	bundle/dmg/BuffBrain_0.1.1_x86_64.dmg
Linux (x86_64)	bundle/deb/buffbrain_0.1.1_amd64.deb
Windows (x86_64)	bundle/nsis/BuffBrain_0.1.1_x64-setup.exe + BuffBrain_0.1.1_x64-setup.nsis

Regenerate Icons

python3 scripts/generate_icons.py

The source logo (src-tauri/icons/buffbrain-logo.png) is the single source of truth. The script generates all PNG sizes, ICNS, ICO, and tray variants from it.

---

✦ Roadmap

• On-device semantic search (MiniLM-L6)
• Heuristic + optional LLM classification
• Tray icon + auto-start
• Settings UI (theme, AI, tray, autostart)
• Linux support (.deb)
• Windows support (.exe + NSIS installer)
• Clipboard history sync (iCloud)
• Multi-device or local network sync
• Custom embedding models (bring your own ONNX)
• Regex-based search filter
• Export/import clipboard history

---

✦ License

MIT © BuffBrain — an open source project by Eulogik.

---

_{Built with ❤️ using Rust, React, and ONNX Runtime.
BuffBrain is crafted by Eulogik — we build tools that think.
BuffBrain — the clipboard manager that actually understands what you copied.}