CBManager

Native macOS menu bar clipboard manager with a Spotlight-style overlay.

Minimum supported OS: macOS 26.

Features

• Menu bar utility (no regular Dock app window)
• Global open shortcut (default: ⌘⇧V, configurable)
• Captures clipboard history for text, links, code, paths, and images
• Fast local fuzzy search
• Image OCR (Vision) for searchable image text
• In-app preview panel toggle with ⌘Y

Keyboard shortcuts

Overlay

• ↑ / ↓ — move selection
• Return — paste selected entry into previous app
• ⌘Y — open/close in-app preview for selected entry
• ⌘D — delete selected entry
• ⌘Z — undo delete
• Esc — close overlay

Preview panel

• ⌘Y — close preview
• Esc — close preview

Development

swift build
swift test
swift run

Fast local reload script (build + kill old process + run):

./scripts/reload-dev.sh

Logs:

tail -f /tmp/cbmanager-dev.log

Build, package, install

Build release app bundle into dist/CBManager.app:

./scripts/build-app.sh 1.0.0

Build DMG into dist/CBManager-<version>.dmg:

./scripts/build-dmg.sh 1.0.0

Install app to /Applications:

./scripts/install.sh

Releases (GitHub)

This repo includes a GitHub Actions workflow: .github/workflows/release.yml.

• Trigger: push a tag like v1.0.0
• Workflow builds release DMG and uploads assets to the matching GitHub Release:
  • CBManager-<version>.dmg
  • CBManager-<version>.dmg.sha256
• Release notes are auto-generated from CHANGELOG.md using:
  • scripts/release-notes-from-changelog.sh
  • Preferred source section: ## [<version>]
  • Fallback source section: ## [Unreleased]

Typical flow

1. Update CHANGELOG.md.
2. (Optional) Preview notes locally:

./scripts/release-notes-from-changelog.sh 1.0.0 CHANGELOG.md /tmp/release-notes.md

3. Tag and push:

git tag -a v1.0.0 -m "v1.0.0"
git push origin main --tags

If the release does not exist yet, create it first:

gh release create v1.0.0 --title "v1.0.0" --notes "placeholder"

Gatekeeper / unsigned app note (xattr)

This project is unsigned (no paid Apple Developer cert/notarization). Downloaded apps may be quarantined by macOS.

After dragging app to /Applications, clear quarantine:

xattr -dr com.apple.quarantine "/Applications/CBManager.app"

You can also right-click the app and choose Open once to allow launch.

Data locations

• SQLite DB: ~/Library/Application Support/CBManager/clipboard.sqlite
• Images: ~/Library/Application Support/CBManager/images/
• App settings (includes global shortcut): ~/Library/Application Support/CBManager/settings.json
• Paste diagnostics log: ~/Library/Application Support/CBManager/paste.log

Search behavior

Search uses an instant local fuzzy ranking pipeline first, then asynchronously appends QMD results without blocking typing or list refresh. QMD keyword search starts at 3+ characters, and semantic search starts at 5+ characters. To keep the overlay responsive, the live list starts with 100 rendered matches and expands the window as you scroll while still searching across the full result set.

Troubleshooting

• Paste doesn’t work
  • Grant Accessibility permission to the installed CBManager.app
  • Check ~/Library/Application Support/CBManager/paste.log for activation and permission diagnostics
• App won’t open after download
  • Use the xattr command above to remove quarantine
• Focus not returning to previous app
  • Reopen once with global shortcut so previous-app reference is refreshed
• Global shortcut should persist across reinstall
  • It is stored in ~/Library/Application Support/CBManager/settings.json
• Want a clean slate
  • Quit app, then remove:
    • ~/Library/Application Support/CBManager/clipboard.sqlite
    • ~/Library/Application Support/CBManager/images/
    • ~/Library/Application Support/CBManager/settings.json

Project docs

• Contributor/agent guidance: AGENTS.md
• Release notes/history: CHANGELOG.md