Maccy Documentation: Complete User Guide for macOS

Q: Where is the configuration stored?

Preferences live in ~/Library/Preferences/org.p0deje.Maccy.plist and can be read or modified with defaults. The history database is in ~/Library/Application Support/Maccy.

Q: Does Maccy replace the system clipboard?

No. It monitors the system pasteboard and keeps its own history database alongside it. No kernel extensions or daemons are installed.

Q: How do I back up my history?

Quit Maccy and copy ~/Library/Application Support/Maccy to your backup drive. To restore, replace the folder and relaunch.

Q: Is there a limit to how many items Maccy remembers?

The default depth is generous and adjustable in Settings -> Storage. Maccy stores lightweight references, so ten thousand entries use under 50 MB on most systems.

Install

Maccy runs on macOS Sonoma 14 or later, as a universal binary on Apple silicon and Intel. Choose the method that fits your workflow.

Direct .dmg

Download the signed and notarised disk image from the official download page. Double-click the .dmg, drag Maccy into Applications, and launch. Because the build is notarised by Apple, Gatekeeper opens it on first launch without warnings. This is the fastest one-off install.

Homebrew

If you already manage tools with Homebrew, run the command below. This pulls the latest signed release and registers the app for automatic updates alongside your other casks. Update later with brew upgrade --cask maccy.

brew install --cask maccy

Build from source

Clone the GitHub repository and open Maccy.xcodeproj in Xcode. The project builds with standard Swift and AppKit frameworks — no external CocoaPods or SPM dependencies required. MIT licensing means you can fork and ship internally without legal review.

Usage & shortcuts

Maccy records everything you copy automatically. Open the history with a keyboard shortcut, type to filter, and press Return to paste. Below is the full default control reference.

Action	Shortcut / method
Open clipboard history	`⌘` `⇧` `C` or click the menu-bar icon
Select and paste	`⌥` `↵` or `⌥`-click
Paste without formatting	`⌥` `⇧` `↵` or `⌥` `⇧`-click
Quick-pick items 1–9	`⌘` `1…9`
Paste without formatting via quick-pick	`⌥` `1…9`
Delete single item	`⌥` `⌫`
Pin or unpin item	`⌥` `P`
Clear unpinned history	Choose Clear or `⌥` `⌘` `⌫`
Clear everything including pinned	Clear with `⇧` `⌥` held, or `⇧` `⌥` `⌘` `⌫`
Disable temporarily	`⌥`-click the menu-bar icon
Ignore next copy only	`⌥` `⇧`-click the menu-bar icon
Open Preferences	`⌘` `,`
Show full-text tooltip	Hover any truncated item for a couple of seconds

Every shortcut is rebindable in Settings → Hotkeys. See the shortcuts reference page for a printable version.

Advanced (defaults)

Fine-tune Maccy with defaults write, custom pasteboard types, and clipboard polling intervals. Preferences are stored in ~/Library/Preferences/org.p0deje.Maccy.plist.

Ignore copied items temporarily

When processing sensitive data, pause recording without quitting. Run the command, do your copies, then revert to false. You can also ⌥-click the menu-bar icon for a temporary toggle.

defaults write org.p0deje.Maccy ignoreEvents true
# ... do your work ...
defaults write org.p0deje.Maccy ignoreEvents false

Ignore custom copy types

Maccy already ignores transient and concealed pasteboard types. To add more, open Preferences → Ignore and enter the type identifier. To discover an app's custom type, use Pasteboard Viewer, copy in the target app, and read the left sidebar. Common entries include de.petermaurer.TransientPasteboardType and com.typeit4me.blocked.

Speed up clipboard check interval

By default Maccy polls the clipboard every 500 ms. For snappier capture, lower the value in seconds. Aggressive polling can slightly increase CPU wake-ups on battery.

defaults write org.p0deje.Maccy clipboardCheckInterval 0.1

Restore hidden footer

If the footer below the history list disappears, re-enable it in Preferences → Appearance. Alternatively, force it via Terminal and restart Maccy.

defaults write org.p0deje.Maccy showFooter 1

Security & privacy

Maccy needs Accessibility access to paste automatically. It never transmits clipboard data off your Mac unless you explicitly enable iCloud sync.

Accessibility permission

When you first try to paste from history, macOS prompts you to grant Maccy control. Approve it in System Settings → Privacy & Security → Accessibility. Without this, Maccy can still copy items to the system clipboard, but cannot simulate the paste keystroke for you.

Concealed pasteboard types

These types are ignored by default because they carry temporary or secret data: org.nspasteboard.TransientType, org.nspasteboard.ConcealedType, org.nspasteboard.AutoGeneratedType, plus com.agilebits.onepassword and similar flags from 1Password, Bitwarden, and Apple Passwords.

Ignore Universal Clipboard

To stop Maccy from recording items copied via Handoff from your iPhone or iPad, add com.apple.is-remote-clipboard to the ignored pasteboard types in Preferences → Ignore.

Per-app blocklist

Add any application to the ignore list in Settings → Ignore. Useful for banking apps, token generators, or VPN clients that handle one-time codes you do not want recorded. Read our privacy policy for the full data-flow diagram.

Troubleshooting

Common issues and how to resolve them without reinstalling.

Why doesn't it paste when I select an item in history?

Make sure Paste automatically is enabled in Preferences.
Ensure Maccy is added to System Settings → Privacy & Security → Accessibility.
Some apps (especially cross-platform Electron or web wrappers) block simulated keystrokes — select the item and press ⌘ V manually.
If the target app runs as Administrator, macOS will not allow Maccy to paste into it. Run both at the same privilege level.

When assigning a hotkey, it says “already used in system settings”

Open System Settings → Keyboard → Keyboard Shortcuts. Under Services → Text, look for entries like Convert text to simplified Chinese or Show Character Viewer. Disable the conflicting shortcut, restart Maccy, and re-assign. We recommend ⌘ ⇧ C because it does not collide with any default macOS binding.

My keyboard shortcut stopped working in password fields

macOS secure-event input blocks shortcuts that produce printable characters (for example ⌥ C outputs “ç”). Remap your summon shortcut to a non-printing combination such as ⌘ ⇧ C. If that is not possible, use Karabiner-Elements to translate your physical shortcut into a neutral one before macOS sees it.

How do I restore the hidden footer?

The footer shows storage stats and the Clear button. If it disappears, open Preferences → Appearance and re-enable it. If the UI refuses, run defaults write org.p0deje.Maccy showFooter 1 in Terminal and restart the app.

How do I ignore copies from Universal Clipboard?

Open Preferences → Ignore, click the plus icon, and add com.apple.is-remote-clipboard. This prevents Maccy from storing items copied via Handoff. Verify by copying something from an iOS device and checking it does not appear in history.

History items disappear after restart

Check Preferences → Storage. If the history size limit is too low, older items are purged on launch. Increase the limit or pin critical items with ⌥ P so they survive cleanup — pinned items are stored separately and never auto-deleted.

Maccy does not start on login

Add Maccy manually to System Settings → General → Login Items. The app intentionally does not install a persistent launch agent, keeping your startup sequence clean and under your control.

Translations

Maccy is localised by the community through Weblate. You can improve an existing translation or add a new language without touching code. All changes are reviewed before merge to ensure consistency with macOS native terminology.

Motivation

There are dozens of clipboard managers for macOS, yet most are either bloated with features nobody asked for or locked behind a subscription. Maccy was built to be as free and focused as Parcellite on Linux — and to teach its author Swift along the way. It is deliberately narrow in scope: a fast, searchable history and nothing else. No snippet expansion, no AI rewriting, no shared workspaces.

License

Maccy is released under the MIT License. You are free to use, modify, distribute, and sublicense it in personal and commercial projects. The full text is available in the GitHub repository.

Documentation questions

Where is the configuration stored?

All preferences live in ~/Library/Preferences/org.p0deje.Maccy.plist and can be read or modified with defaults read/write. The clipboard history database is stored separately in ~/Library/Application Support/Maccy. To back up your history, quit Maccy and copy that folder.

Can I run Maccy on macOS Ventura or older?

Maccy 2.7.3 officially supports macOS Sonoma 14 and later. Legacy builds for older systems may exist in the GitHub release archive, but they are unmaintained and lack security fixes.

Does Maccy replace the system clipboard?

No. It monitors the system pasteboard and maintains its own history database alongside it. You can uninstall Maccy at any time and your system clipboard continues to work normally. No kernel extensions or background daemons are installed.

How do I back up my history?

Quit Maccy, then copy ~/Library/Application Support/Maccy to your backup drive. To restore, quit Maccy, replace the folder, and relaunch. If you use iCloud sync, the data is already mirrored across your signed-in Macs.

Is there a limit to how many items Maccy remembers?

The default history depth is generous, and you can adjust it in Settings → Storage. Storage impact stays tiny because Maccy stores lightweight references and previews, not duplicated file contents. Ten thousand entries consume less than 50 MB on most systems.

Documentation