copippe User Guide

1. Getting Started

Installation

1. Download copippe-v0.2-macOS.dmg or .zip from GitHub Releases
2. Open the DMG and drag copippe.app to your Applications folder
3. Launch copippe from Applications

System Requirements

• macOS 14 (Sonoma) or later
• Apple Silicon or Intel Mac

Once launched, copippe appears as a clipboard icon in the menu bar. There is no Dock icon — the app runs entirely from the menu bar.

2. Menu Bar

Click the clipboard icon in the menu bar to open the dropdown menu. The icon changes depending on the current mode:

The dropdown menu contains:

• Active/Inactive toggle — Switch plain text mode on or off
• Clipboard history — Recent text and image entries
• Snippet folders — Expandable submenus with registered snippets
• Preferences... — Open the settings window
• Quit — Exit the app

3. Clipboard History

Every time you copy text or an image, copippe saves it to the history list. You can store up to 30 entries by default (configurable up to 100 in Preferences).

How it works

1. Copy something as usual (Cmd+C)
2. copippe automatically captures it
3. Click the menu bar icon to see your history
4. Click any entry to put it back on your clipboard
5. Paste with Cmd+V

Behavior details

• Deduplication — If you copy the same text again, the old entry is moved to the top instead of creating a duplicate
• Empty text is ignored — Whitespace-only copies are not saved
• Persistent — History is saved to disk and restored when the app restarts
• FIFO — When the history is full, the oldest entry is removed automatically

4. Plain Text Mode

When Active, copippe automatically strips all rich text formatting (HTML, RTF, styles) from copied text and replaces the clipboard content with plain text.

What gets stripped

• Font styles (bold, italic, colors, sizes)
• HTML markup from web pages
• RTF formatting from documents
• Any non-text content when text is available

What stays unchanged

• Images — copied images pass through without modification
• The text content itself — only formatting is removed, not the words

Toggle between Active and Inactive from the menu bar dropdown, or use Cmd+A when the menu is open.

5. Image History

copippe captures copied images alongside text entries in a unified history list.

• Images are saved as PNG files in ~/Library/Application Support/copippe/images/
• Thumbnails are generated for display in the menu and popup
• Click an image entry to restore it to the clipboard
• When an image entry is removed from history, the file is cleaned up automatically

6. Snippet Management

Snippets let you save frequently used text for instant pasting. They are organized in folders.

Creating snippets

1. Open Preferences → Snippets tab
2. Click + under the folder list to create a folder
3. Select the folder, then click + under the snippet list
4. Enter a title and content, then click Save

Using snippets

• From the menu bar: Click the copippe icon → expand a folder submenu → click a snippet to copy it
• From the popup: Press Ctrl+Option+V, switch to the Snippets tab, and click a snippet
• Via hotkey: Assign a global hotkey to a snippet in Preferences and press it from any app

Managing snippets

• Edit — Select a snippet and click the pencil icon
• Delete — Select a snippet or folder and click −
• Move between folders — Supported via the Preferences UI
• Search — Search by title or content in the popup window

Snippet data is stored in ~/Library/Application Support/copippe/snippets.json.

7. Search Popup

The floating search popup gives you fast access to your history and snippets from any application.

Opening the popup

Press Ctrl+Option+V from any app. The popup appears as a floating panel that stays on top of other windows.

Using the popup

1. Search — Type in the search field to filter entries in real time
2. Switch tabs — Toggle between History and Snippets using the tab bar
3. Navigate — Use ↑ / ↓ to move between entries
4. Select — Click an entry or press Enter to copy it to the clipboard and close the popup
5. Close — Press Esc or click outside the popup

History tab

• Shows text entries with a preview and image entries with thumbnails
• Search filters text entries only (images are excluded from search results)

Snippets tab

• Shows all snippets organized by folder when not searching
• Shows flat search results when a query is entered
• Displays assigned hotkey badges next to snippets

8. Global Hotkeys

Global hotkeys work from any application, even when copippe is not in the foreground.

Default hotkeys

Customizing hotkeys

1. Open Preferences → Hotkeys tab
2. Click the recorder button next to the action
3. Press your desired key combination
4. If a conflict is detected, you will be warned

Per-snippet hotkeys

You can assign a unique global hotkey to any snippet. When pressed, the snippet's content is immediately copied to the clipboard — no popup needed.

Set per-snippet hotkeys in Preferences → Snippets when editing a snippet.

9. Preferences

Open from the menu bar dropdown by clicking Preferences... (Cmd+,).

General tab

Hotkeys tab

Configure the global keyboard shortcut to open the search popup. See Global Hotkeys for details.

Snippets tab

Manage folders and snippets. See Snippet Management for details.

10. Keyboard Shortcuts

Global (works from any app)

Menu bar dropdown (when open)

Search popup (when open)

11. Troubleshooting

App is blocked on first launch

copippe is not notarized by Apple. Run the following command in Terminal:

xattr -cr /Applications/copippe.app

Or go to System Settings → Privacy & Security and click Open Anyway.

Global hotkeys don't work

• Make sure copippe has Accessibility permission: System Settings → Privacy & Security → Accessibility
• Check for conflicts with other apps using the same key combination
• Try setting a different hotkey in Preferences → Hotkeys

History is not being captured

• Make sure copippe is running (check for the clipboard icon in the menu bar)
• copippe captures clipboard changes via polling — there may be a short delay (up to 0.5 seconds)

Data locations