Skip to content

README.md

Latest commit

 

History

History
155 lines (109 loc) · 4.13 KB

README.md

File metadata and controls

155 lines (109 loc) · 4.13 KB
Raw

CBManager

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

Minimum supported OS: macOS 26.

CBManager overlay

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
  1. 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