Maccy Documentation

Lightweight clipboard manager for macOS

22,030 stars Swift Swift 2 files · ~2,874 tokens #clipboard-manager#maccy#macos
RAW Doc

Technical Documentation: p0deje/Maccy

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

[!WARNING]
Beware of fake websites impersonating Maccy. Malicious sites (such as maccyapp.net and maccyapp.com) distribute malware disguised as Maccy. maccy.app is the only official website.

[Maccy](https://maccy.app)


Maccy is a lightweight clipboard manager for macOS. It keeps the history of what you copy
and lets you quickly navigate, search, and use previous clipboard contents.

Maccy works on macOS Sonoma 14 or higher.

Features

  • Lightweight and fast
  • Keyboard-first
  • Secure and private
  • Native UI
  • Open source and free

Install

Download the latest version from the releases page, or use Homebrew:

sh
brew install maccy

Usage

  1. SHIFT (⇧) + COMMAND (⌘) + C to popup Maccy or click on its icon in the menu bar.
  2. Type what you want to find.
  3. To select the history item you wish to copy, press ENTER, or click the item, or use COMMAND (⌘) + n shortcut.
  4. To choose the history item and paste, press OPTION (⌥) + ENTER, or OPTION (⌥) + CLICK the item, or use OPTION (⌥) + n shortcut.
  5. To choose the history item and paste without formatting, press OPTION (⌥) + SHIFT (⇧) + ENTER, or OPTION (⌥) + SHIFT (⇧) + CLICK the item, or use OPTION (⌥) + SHIFT (⇧) + n shortcut.
  6. To delete the history item, press OPTION (⌥) + DELETE (⌫).
  7. To see the full text of the history item, wait a couple of seconds for tooltip.
  8. To pin the history item so that it remains on top of the list, press OPTION (⌥) + P. The item will be moved to the top with a random but permanent keyboard shortcut. To unpin it, press OPTION (⌥) + P again.
  9. To clear all unpinned items, select Clear in the menu, or press OPTION (⌥) + COMMAND (⌘) + DELETE (⌫). To clear all items including pinned, select Clear in the menu with OPTION (⌥) pressed, or press SHIFT (⇧) + OPTION (⌥) + COMMAND (⌘) + DELETE (⌫).
  10. To disable Maccy and ignore new copies, click on the menu icon with OPTION (⌥) pressed.
  11. To ignore only the next copy, click on the menu icon with OPTION (⌥) + SHIFT (⇧) pressed.
  12. To customize the behavior, check "Preferences…" window, or press COMMAND (⌘) + ,.

Advanced

Ignore Copied Items

You can tell Maccy to ignore all copied items:

sh
defaults write org.p0deje.Maccy ignoreEvents true # default is false

This is useful if you have some workflow for copying sensitive data. You can set ignoreEvents to true, copy the data and set ignoreEvents back to false.

You can also click the menu icon with OPTION (⌥) pressed. To ignore only the next copy, click with OPTION (⌥) + SHIFT (⇧) pressed.

Ignore Custom Copy Types

By default Maccy will ignore certain copy types that are considered to be confidential
or temporary. The default list always include the following types:

  • org.nspasteboard.TransientType
  • org.nspasteboard.ConcealedType
  • org.nspasteboard.AutoGeneratedType

Also, default configuration includes the following types but they can be removed
or overwritten:

  • com.agilebits.onepassword
  • com.typeit4me.clipping
  • de.petermaurer.TransientPasteboardType
  • Pasteboard generator type
  • net.antelle.keeweb

You can add additional custom types using settings.
To find what custom types are used by an application, you can use
free application Pasteboard-Viewer.
Simply download the application, open it, copy something from the application you
want to ignore and look for any custom types in the left sidebar. Here is an example
of using this approach to ignore Adobe InDesign.

Speed up Clipboard Check Interval

By default, Maccy checks clipboard every 500 ms, which should be enough for most users. If you want
to speed it up, you can change it with defaults:

sh
defaults write org.p0deje.Maccy clipboardCheckInterval 0.1 # 100 ms

FAQ

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

  1. Make sure you have "Paste automatically" enabled in Preferences.
  2. Make sure "Maccy" is added to System Settings -> Privacy & Security -> Accessibility.

When assigning a hotkey to open Maccy, it says that this hotkey is already used in some system setting.

  1. Open System settings -> Keyboard -> Keyboard Shortcuts.
  2. Find where that hotkey is used. For example, "Convert text to simplified Chinese" is under Services -> Text.
  3. Disable that hotkey or remove assigned combination (screenshot).
  4. Restart Maccy.
  5. Assign hotkey in Maccy settings.
  1. Open Maccy window.
  2. Press COMMAND (⌘) + , to open preferences.
  3. Enable footer in Appearance section.

If for some reason it doesn't work, run the following command in Terminal.app:

sh
defaults write org.p0deje.Maccy showFooter 1

How to ignore copies from [Universal Clipboard](https://support.apple.com/en-us/102430)?

  1. Open Preferences -> Ignore -> Pasteboard Types.
  2. Add com.apple.is-remote-clipboard.

My keyboard shortcut stopped working in password fields. How do I fix this?

If your shortcut produces a character (like Option+C → "ç"), macOS security may block it in password fields. Use Karabiner-Elements to remap your shortcut to a different combination like Cmd+Shift+C. See detailed solution.

Translations

The translations are hosted in Weblate.
You can use it to suggest changes in translations and localize the application to a new language.

Motivation

There are dozens of similar applications out there, so why build another?
Over the past years since I moved from Linux to macOS, I struggled to find
a clipboard manager that is as free and simple as Parcellite,
but I couldn't. So I've decided to build one.

Also, I wanted to learn Swift and get acquainted with macOS application development.

License

MIT

Keyboard Shortcut Password Fields (`docs/keyboard-shortcut-password-fields.md`)

Keyboard Shortcut Not Working in Password Fields

Problem Description

Some users may experience issues where their Maccy keyboard shortcut stops working, particularly in password fields or secure input contexts. This commonly occurs when using shortcuts that produce visible characters, such as Option+C which generates the "ç" character.

Root Cause

macOS blocks keyboard event listeners that output text in secure fields. When a keyboard combination generates a character (like Option+C → "ç"), macOS security features prevent third-party applications from intercepting these key events in password fields and other secure input contexts.

Easy Solution

Choose Different Shortcut: Select a keyboard combination that doesn't produce visible characters (e.g., Cmd+Shift+V)

Detailed Solution: If you really want to continue using your current kb shortcut

If you want to use a keyboard shortcut that is used by the system (and produces text output), you can use Karabiner-Elements to remap this shortcut to another keyboard shortcut. For example, remapping Option+C to Cmd+Shift+C.

Using Karabiner-Elements

  1. Download and Install Karabiner-Elements

  2. Configure Key Remapping

    • Open Karabiner-Elements
    • Navigate to "Complex Modifications"
    • Click 'Add your own rule'
    • Paste the following JSON configuration (see example below)
    • Instructions for editing different key combinations: modify the key_code and modifiers values as needed
    • Give your rule a name (Example: "Remap Option+C to Cmd+Shift+C for clipboard manager")

  3. Example Karabiner Rule
    This example remaps Option+C to Cmd+Shift+C:

    json
    {
  "description": "Remap option+c to cmd+shift+c for Maccy trigger",
  "manipulators": [
    {
      "from": {
        "key_code": "c",
        "modifiers": {
          "mandatory": ["left_alt"],
          "optional": ["any"]
        }
      },
      "to": [
        {
          "key_code": "c",
          "modifiers": ["left_command", "left_shift"]
        }
      ],
      "type": "basic"
    }
  ]
}

  4. Update Maccy Settings

    • Open Maccy preferences
    • Set the keyboard shortcut to match your Karabiner remapping (in this example: Cmd+Shift+C)
    • Test the shortcut in various contexts, including password fields

Alternative Solutions

  • Choose Different Shortcut: Select a keyboard combination that doesn't produce visible characters (e.g., Cmd+Shift+V)
  • System Keyboard Settings: Modify system keyboard shortcuts that might conflict with your desired combination

Verification

After implementing the solution:

  1. Test the shortcut in regular text fields
  2. Test the shortcut in password fields
  3. Test the shortcut in secure applications (banking apps, password managers)
  4. Verify Maccy responds consistently across all contexts

This approach allows you to continue using your preferred key combination while ensuring compatibility with macOS security features.

--- METRICS ---

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#clipboard-manager Browse clipboard-manager catalog → #maccy Browse maccy catalog → #macos Browse macos catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →