ClipFlow

A native macOS clipboard history manager + screenshot tool, built the way it should be.

Single click to paste. Screenshots saved to disk and clipboard. No focus stealing. Open-source, free, and works the way Windows Win+V should have worked on the Mac all along.

---

✨ Features

• 🗂 Clipboard history — text, images, links, files and colors, up to 100 items (pinned items don't count against the limit).
• 🔍 Text recognition — ⌘⇧2 grabs the text out of any region of the screen straight to the clipboard, and screenshots in your history become searchable by what they say. Runs on device via Vision; nothing leaves the Mac.
• 📸 Screenshots → clipboard and disk simultaneously — ⌘⇧4/3/5 saves to ~/Desktop/Screenshots/ and copies to the clipboard, with a preview in the history.
• ⌨️ Single-click paste — click an item and it pastes directly into the app you were typing in. No double-clicks. No manual ⌘V.
• 🪟 Non-focus-stealing panel — Spotlight-style NSPanel keeps your typing focus intact in the underlying app, so the synthetic ⌘V always lands where you expect.
• 🔍 Live search & filters — search by content or source app, filter by type (text / images / links / files).
• 📌 Pin important items — pinned entries are preserved when the 100-item cap rotates out older clips.
• 🎯 Source app tracking — every clip records the app it came from.
• 🛡 Privacy-aware — respects org.nspasteboard.ConcealedType so passwords from 1Password, Bitwarden, etc. are never logged.
• 🍎 Native Swift + SwiftUI — universal binary (Apple Silicon + Intel), ~11 MB, <30 MB RAM idle.

🚀 Quick start

Download (recommended)

Grab the latest .dmg from the Releases page, drag ClipFlow.app to /Applications, right-click → Open the first time (Gatekeeper warning is expected — the app is signed ad-hoc, not with a $99/year Developer ID).

Then run the permission helper:

bash /Volumes/ClipFlow*/Scripts/grant-permissions.sh

It guides you through the two macOS permission switches (Screen Recording + Accessibility) and disables the native screenshot shortcuts that would otherwise collide with ClipFlow's.

Build from source

Requires macOS 26 Tahoe+ and Xcode 26+ with Swift 5.9+. The UI is built on Liquid Glass (glassEffect, GlassEffectContainer, scrollEdgeEffectStyle), which is only available from macOS 26 onwards.

git clone https://github.com/Unixcision/clipflow.git
cd clipflow
bash scripts/install.sh

That script compiles a release universal binary, packages it as ClipFlow.app, copies it to /Applications, and launches it. The first time you trigger a screenshot or open the history, macOS will prompt for the required permissions.

🎹 Default shortcuts

Shortcut	Action
⌃⌘V	Open the clipboard history panel
⌘⇧4	Selection screenshot (clipboard + Desktop/Screenshots)
⌘⇧3	Full-screen screenshot
⌘⇧5	Window screenshot
Esc	Close the panel
↑ ↓	Navigate history while panel is open
Return	Paste the selected item

All shortcuts are remappable from the menubar icon → Preferences.

🏗 Architecture

Sources/ClipFlow/
├── App/                # Entry point & coordinator
│   ├── ClipFlowApp.swift
│   └── AppCoordinator.swift
├── Clipboard/          # Pasteboard monitor + SQLite store
│   ├── ClipboardItem.swift
│   ├── ClipboardMonitor.swift   ← polls NSPasteboard.changeCount @ 0.5 Hz
│   └── ClipboardStore.swift     ← GRDB + on-disk blobs for images
├── Screenshot/         # screencapture(1) wrapper
│   └── ScreenshotService.swift  ← uses `-c` to skip the Tahoe rect-bug
├── Hotkeys/            # Global shortcut registration
│   └── HotkeyManager.swift      ← KeyboardShortcuts (Sindre Sorhus)
├── UI/                 # SwiftUI views + AppKit shell
│   ├── HistoryView.swift
│   ├── HistoryWindowController.swift  ← NSPanel + .nonactivatingPanel
│   ├── MenuBarController.swift
│   └── PreferencesView.swift
└── Utils/
    ├── Log.swift                 ← os.Logger with category subsystems
    └── LaunchAtLogin.swift       ← SMAppService wrapper

Key design decisions

• NSPanel with .nonactivatingPanel instead of NSWindow — same pattern as Spotlight, Raycast and Alfred. The panel receives keyboard events without stealing the underlying app's key/main status, so when you click an item, the synthetic ⌘V is delivered to the original app and not to ClipFlow itself.
• CGEvent.post(tap: .cgSessionEventTap) for the paste injection — matches Maccy's approach; events flow through the same tap as real key presses, with setLocalEventsFilterDuringSuppressionState to prevent interleaving with the user's own keystrokes.
• screencapture -c (clipboard target, no temp file) — sidesteps the macOS 26 (Tahoe) screencapture -i ... file.png bug where the daemon returns could not create image from rect for ad-hoc signed processes.
• Image blobs on disk, not in SQLite — screenshots can be several MB; storing them as separate PNG files in ~/Library/Application Support/ClipFlow/blobs/ keeps the DB lean.
• Spotlight clipboard history is not relied upon — macOS Tahoe's built-in clipboard panel only keeps 7 days of plain-text and logs passwords. ClipFlow filters concealed pasteboard types and gives you a real archive.

🔐 Permissions

ClipFlow asks for two permissions on first use:

1. Screen Recording — required for screencapture. Without it, screenshot shortcuts will fail silently.
2. Accessibility — required for the global hotkey (KeyboardShortcuts uses Carbon RegisterEventHotKey) and for injecting the synthetic ⌘V after picking an item.

The bundled scripts/grant-permissions.sh automates everything that can be automated (TCC cleanup of stale entries from earlier builds, disabling the native screenshot shortcuts) and walks you to the exact System Settings panes for the two manual toggles. macOS forbids any program — even with sudo — from setting TCC entries itself; that's by design and not something ClipFlow can or should work around.

💾 Data

What	Where
Clipboard history (SQLite)	~/Library/Application Support/ClipFlow/clipboard.sqlite
Image blobs	~/Library/Application Support/ClipFlow/blobs/
Screenshots	~/Desktop/Screenshots/
Preferences	defaults read com.unixcision.clipflow

To wipe everything: bash scripts/uninstall.sh.

🛠 Development

swift build              # debug build
swift build -c release   # release build (universal if you pass --arch arm64 --arch x86_64)
swift run ClipFlow       # run from the build folder

Logs are emitted via os.Logger under subsystem com.unixcision.clipflow:

log stream --predicate 'subsystem == "com.unixcision.clipflow"' --info

Categories: app, clipboard, hotkeys, screenshot.

🤝 Contributing

Issues and pull requests welcome. If you spot a bug, please attach the relevant log show … --last 5m output for the com.unixcision.clipflow subsystem.

📜 License

MIT — see LICENSE.

🙏 Credits

• Sindre Sorhus — KeyboardShortcuts Swift package
• groue — GRDB.swift SQLite toolkit
• Maccy — reference implementation for clipboard monitoring patterns and CGEvent paste injection
• App icon generated with Google's Imagen 4