ClipBored is a small native macOS clipboard manager. It captures local clipboard history and opens a keyboard-first responsive bottom panel for search, sorting, copy, paste, pinning, and deletion. It runs as a dockless menu-bar utility by default, with an optional Dock icon mode.

The project is intentionally dependency-light: Swift Package Manager, AppKit, Carbon hotkeys, SQLite, and system frameworks only.

Features

Dockless menu-bar utility by default (LSUIElement=true), with a Settings toggle for normal Dock presence
Right-click menu-bar status menu with capture state, history count, settings, pause/resume, and quit
Global shortcuts:
- Command + Option + V toggles the clipboard panel
- Command + , opens settings
- Command + 1 through Command + 9 paste the numbered visible card; add Shift to paste that card as plain text
- Command + G shows a filtered result back in the full clipboard history
- Shift + Command + N creates a new collection
- Space previews the selected card when the focused search field is empty
Clipboard history for text, URLs with local preview thumbnails when available, images, audio, RTF/HTML rich text, PDFs, and file references
Keyboard-focusable cards and collection chips with type-to-search, Return-to-paste/select, Space-to-preview for text, links, files, and media, vertical wheel/trackpad panning and overflow edge fades in horizontal rails, visible focus chrome, and VoiceOver action hints
Shelf navigation keys for focused cards: Left/Right, Page Up/Page Down, Home, and End
Shelf navigation keys for focused collection chips: Left/Right, Home, and End
SQLite persistence with bounded history, pinned-item retention, and encrypted app-managed payloads
Search with independent token matching, structured filters such as app:Safari, type:image,pdf, pinboard:"Client Work","Read Later", date:2026-06-30, result jump-back to full history, and optional local OCR for copied images
Sort modes for recent, most used, images, links, text, files, audio, and pinned items
Custom named collections, including empty color-coded collections, for organizing clips from the card Collect control, context menu, keyboard-focusable collection rail, or by dragging cards onto collection chips; collection chips can be edited or deleted from their context menu
Searchable custom titles for clips, so media, files, links, PDFs, audio, and text can be renamed without changing the copied payload
Copy and paste actions with Accessibility permission fallback
Image thumbnail cache with byte and file-count pruning
Configurable history length, cache limit, polling profile, ignored apps, content kinds, launch-at-login, Dock/menu-bar presence, and clear-on-quit behavior, with card-level capture rules for ignoring a source app or content type
Local-only storage, with optional sensitive-content exclusion for common secrets

Requirements

macOS 13 or newer
Xcode command line tools with Swift 5.9 or newer

Build

swift test
./scripts/build-macos-app.sh
open build/ClipBored.app

The build script packages build/ClipBored.app, strips the executable, applies an ad-hoc hardened-runtime signature, and enforces a 1 MiB executable gate plus a 1.8 MB bundle gate.

Development

Run the full local validation:

./scripts/check.sh

Useful commands:

swift test -q
./scripts/build-macos-app.sh
./scripts/release-macos-app.sh
./scripts/idle-soak-report.sh 900

For app-level behavior that cannot be fully covered by unit tests, run the manual checklist in docs/SMOKE_TEST.md. For distribution builds, see docs/RELEASE.md.

Project layout:

sources/clipbored/app - app entry point and service wiring
sources/clipbored/config - defaults and power/size guardrails
sources/clipbored/extensions - small AppKit/Foundation helpers
sources/clipbored/models - clipboard item and settings models
sources/clipbored/resources - app bundle metadata and icon assets
sources/clipbored/services - clipboard capture, persistence, cache, shortcuts, paste, diagnostics, privacy filters
sources/clipbored/views - panel and settings UI
tests/clipboredtests - unit tests for persistence, filtering, shortcuts, pasteboard writes, diagnostics, and sensitive-content detection
docs - architecture, security notes, and roadmap

Privacy And Security

ClipBored does not use network APIs or telemetry. Clipboard history is stored locally under Application Support.

Textual SQLite fields, image cache files, audio clips, rich text sidecars, and PDF attachments are encrypted with AES-GCM using a Keychain-held key when Keychain access is available. If Keychain access blocks or fails, ClipBored uses an owner-only app-local fallback key so capture does not stall. Full history clears remove the local fallback key when present and reset cached key state for future captures. Temporary decrypted preview files may be created when opening or revealing encrypted media; stale previews are cleared on launch, cache/history clear, and quit. Use sensitive-content exclusion and ignored app settings for high-risk sources. See docs/SECURITY.md for details and responsible disclosure.

Contributing

See CONTRIBUTING.md. The current roadmap is in docs/ROADMAP.md.

License

GPL-2.0-only. See LICENSE.