Maclipboard

README in 中文

A lightweight, fast, and minimalistic clipboard manager for macOS built purely with SwiftUI. It runs invisibly in the background, keeping track of your clipboard history, and allows you to quickly access and auto-paste previously copied items.

💡 Why Maclipboard?

Compared to other similar products, Maclipboard is super light (small but complete in every detail), features a more native Apple UI, and provides a more intuitive user experience and keyboard shortcuts.

✨ Features

• Custom Global Hotkey: Instantly bring up your clipboard history from any application. The default is CONTROL (⌃) + V, but can be re-recorded to any key combination in Settings!
• Keyboard-Driven Auto-Paste: Navigate your history with the UP (↑) and DOWN (↓) keys and press RETURN (⏎), or simply click an item, to automatically paste it directly into your active window.
• Categorized Tabs: Use the LEFT (←) and RIGHT (→) arrow keys to quickly swap between viewing All history, Pinned items, Images, or Files.
• Advanced Item Actions: While selecting an item with the arrow keys:
  • SPACE: Open a full-text preview overlay of the selected item's content.
  • CONTROL (⌃) + P: Toggle the pin status of the selected item directly from your keyboard.
  • COMMAND (⌘) + BACKSPACE (⌫): Permanently delete the selected item from your history.
  • COMMAND (⌘) + SHIFT (⇧) + BACKSPACE (⌫): Delete all unpinned items instantly.
• Rich Media Support: Maclipboard isn't just for text!
  • Files: Copies actual files and folders from Finder (via their path), displaying native document icons and allowing you to automatically paste them anywhere.
  • Native Screenshots: Silently monitors your designated screenshot directory (default: ~/Desktop). Whenever you take a standard macOS screenshot (COMMAND (⌘) + SHIFT (⇧) + 4 or COMMAND (⌘) + SHIFT (⇧) + 5), Maclipboard intercepts the new image and instantly adds it to your clipboard history!
• Rich Customization: Click the Gear icon in the panel header to access native settings:
  • Appearance Themes: Force Light mode, Dark mode, or inherit dynamically from the macOS System.
  • Background Images: Select any local photo from your Mac to automatically stretch across the panel background.
  • Opacity & Blur Control: Adjust the background transparency slider, and optionally toggle a frosted glass blur effect that dynamically filters your chosen background image or color.
  • Custom Colors: Pick a specific tint color for the panel background using the native macOS Color Picker.
  • Custom Screenshot Folder: Change the folder Maclipboard monitors for screenshot files.
  • Behavior Setup: Enable "Launch at Login" for automatic startup, or toggle "Clear History on Quit" to protect your privacy.

🚀 Installation & Usage

1. Download Pre-built Installer (Quickest)

Download the latest .dmg installer from the GitHub Releases page. Open the downloaded file and drag the Maclipboard application into the provided Applications folder shortcut!

2. Build from Source

Maclipboard is built purely natively and requires no heavy JavaScript dependencies. A convenient Makefile is included if you prefer to build the application from source.

Prerequisites

• macOS 13.0 or higher.
• Xcode Command Line Tools installed. (You can install them by running xcode-select --install in your terminal).

Running the App

1. Open your terminal and navigate to the root folder of this project.
2. Run the following command to compile and launch the application immediately:

   make run

3. Alternatively, if you only want to build the Maclipboard.app bundle into the build/ directory without launching it, run:

   make app

4. To create a drag-to-install DMG, run:

   make dmg

   (Requires create-dmg which can be installed via brew install create-dmg)
5. To clean the build directory and start completely fresh, run:

   make clean

⚙️ Troubleshooting Permissions

Because Maclipboard needs to listen for the global CONTROL (⌃) + V hotkey while running in the background, and needs to simulate COMMAND (⌘) + V keystrokes for the Auto-Paste feature, it strictly requires Accessibility permissions from macOS.

Additionally, to provide "Native Screenshot" support (COMMAND (⌘) + SHIFT (⇧) + 4 / COMMAND (⌘) + SHIFT (⇧) + 5), Maclipboard requires Desktop Folder access. This allows it to briefly detect when macOS natively drops a new screenshot onto your Desktop so it can read the image into your clipboard history.

If pressing the hotkey does not open the panel, or if clicking an item does not paste it into your active app:

1. Open System Settings > Privacy & Security > Accessibility.
2. Find Maclipboard in the list of applications.
3. Ensure the toggle switch next to Maclipboard is turned ON.

Note: If permissions are granted but the app still isn't responding (common when rapidly rebuilding the application from source), macOS may have cached an old signature. Select Maclipboard in the Accessibility list, click the minus (-) button to remove it entirely, then run make run again to prompt a brand new permission dialog from the operating system.