EasyPaste

Four recent copies, one small wheel. A native macOS menu bar app built with Swift, AppKit, and SwiftUI.

Hold Control + Option + V, move the pointer to a copy, then release Control and Option to paste. Normal Command-V still works as usual.

Set up

Requires macOS 13 or later and Xcode Command Line Tools with Swift 5.9 or later. There are no external packages, accounts, API keys, or paid services. The full check script uses swift format, which requires a Swift 6 toolchain (Xcode 16 or later).

1. If developer tools are missing, run xcode-select --install and complete the macOS installer. Check the tools:

   swift --version
   xcrun --find swift

2. Clone the repository and enter its directory. If you already have a local copy, open Terminal there instead.

   git clone https://github.com/anthnykr/easy-paste.git
   cd easy-paste

3. Build the app:

   ./scripts/build.sh

   Success ends with Built .../dist/EasyPaste.app. The script builds a release executable, creates the icon, packages the app, and verifies its local code signature. It does not install or launch the app.

4. Start it:

   open dist/EasyPaste.app

   A clipboard icon appears in the menu bar. EasyPaste has no Dock icon. On first launch, a setup dialog appears.

5. Enable System Settings > Privacy & Security > Accessibility > EasyPaste. Use the + button if it is missing. In the file picker, press Command-Shift-G and enter the full path to dist/EasyPaste.app. This step requires a person to approve the permission. It cannot be completed by the build script.

You can keep the app in dist, or move it to Applications before granting Accessibility access. Quit the app before rebuilding or replacing it. Run the same copy of the app that you granted access to.

Use

• The newest copy is at the top. Older copies go right, bottom, then left.
• Release in the centre, over an empty slot, or outside the wheel to cancel. Escape also cancels. You must move the pointer before hold mode selects an item.
• Prefer clicking? Enable Click to paste in the menu. Press the shortcut once, then click a card. Click the centre or press Escape to cancel.
• Open wheel in the menu always uses click mode.
• Shortcut offers Control + Option with V, B, or Space. If registration fails, the app reports a conflict.
• Pause clipboard history stops new capture. Existing copies remain available.
• Clear history removes the four saved copies. It does not clear the system clipboard.
• Selecting a copy does not reorder the wheel. Copying the same content again moves it to the top.
• The selected copy becomes the system clipboard, so the next Command-V pastes it again.

The wheel opens near the pointer and stays inside the screen. Near a screen edge, its centre can shift away from the pointer.

Data and limits

History stays in memory. Quit EasyPaste to clear it. The app makes no network requests and writes no clipboard history to disk. Only shortcut, interaction mode, and welcome-screen preferences are saved in UserDefaults.

Text, RTF, HTML, PNG, and TIFF representations are kept when available. File-only copies and multi-item clipboard payloads are skipped. Screenshots that include both image data and a file reference, such as CleanShot copies, are kept as images. The file reference is not stored or opened. Each copy is limited to 20 MiB across its supported representations. The app checks for changes every 300 ms, so copies made faster than that can be missed. Only new copies made while the app is running are captured.

Copies marked concealed, transient, or auto-generated are skipped. These markers depend on the source app. Unmarked passwords or other private text can still enter history. Pause capture before copying content you do not want saved.

Accessibility access is used to send Command-V to the original app. Without it, you can view history, but automatic paste is unavailable. Some apps or protected fields can reject simulated paste commands. Clipboard access may also require approval on macOS versions that request it.

Troubleshooting

Problem	Action
swift is missing	Install Command Line Tools with xcode-select --install.
swift format is missing	Use Xcode 16 or later for the full check script. ./scripts/build.sh does not need the formatter.
Wrong developer tools are selected	Check xcode-select -p. If needed, select your Xcode installation in Xcode Settings > Locations.
No main window appears	This is a menu bar app. Find the clipboard icon, or press its shortcut.
Wheel is empty	Copy text or an image after launch. Check that capture is not paused. Files and large items are skipped.
Shortcut does nothing	Choose another shortcut from the menu. Quit other copies of EasyPaste.
Wheel opens but paste fails	Check Accessibility access for the exact app copy you are running. Try a normal TextEdit document. Release all modifier keys.
Permission stopped working after a rebuild	Quit EasyPaste. Remove its old entry in Accessibility settings, add the rebuilt app, enable it, and launch it again.

The build automatically uses your Apple Development signing identity when exactly one is available. This keeps the app identity stable across rebuilds. If you have several identities, select one with SIGNING_IDENTITY="Your signing identity" ./scripts/build.sh. Use the same identity for later builds.

Without a development identity, the build uses an ad-hoc signature and prints a notice. Changed builds can then require Accessibility approval again. Normal restarts of an unchanged app should retain access. Moving from ad-hoc signing to a development identity requires one new approval. To use ad-hoc signing explicitly, run SIGNING_IDENTITY=- ./scripts/build.sh. Public downloads need a separate Developer ID signing and notarization process; this repository does not include a notarized release.

Project layout

• Sources/EasyPaste: clipboard capture, global shortcut, wheel, menu, permissions, and paste delivery.
• Sources/EasyPasteCore: history and pointer-selection rules.
• Tests/EasyPasteCoreTests: core and clipboard integration tests.
• Resources: app metadata and icon source.
• scripts: build, icon conversion, and full checks.

Small, focused contributions are welcome. Describe the issue, make the change, run ./scripts/check.sh, and include the result and any manual checks in the pull request. Keep clipboard data out of logs and bug reports.

License

MIT. See LICENSE. The icon was created with Codex image generation. Its prompt is in Resources/ICON.md.