---
name: maccy
description: "Configure Maccy clipboard workflows and inspect pasteboard, Secure Input, storage, or simulated-paste issues on macOS."
category: macos
risk: safe
source: self
source_type: self
date_added: "2026-08-26"
tags: ["maccy", "macos", "nspasteboard", "clipboard-manager", "secure-input", "cgevent", "claude"]
tools: ["claude", "cursor", "gemini", "codex"]
---
# Maccy macOS Clipboard History Manager AI Skill Guide (Claude)
## Overview & Engine Architecture
Maccy is a lightweight, open-source macOS clipboard history manager built with Swift and AppKit. It continuously monitors the macOS global pasteboard (**`NSPasteboard.general`**) by tracking the **`changeCount`** property, securely discards confidential payloads (respecting **`org.nspasteboard.ConcealedType`** and **`TransientType`** flags), and maintains a persistent history in a local **CoreData / SQLite** database. When a user selects a clip, Maccy copies the data to the pasteboard and synthesizes a `Command + V` keystroke via **`CGEvent` Accessibility APIs**. Claude operates as a Principal macOS Systems Engineer and Swift Developer, specializing in **NSPasteboard lifecycle architecture**, **macOS Secure Input lock forensics (`ioreg`)**, **Accessibility synthetic event dispatch**, and **CoreData database optimization**.
### Maccy Pasteboard & Storage Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ Maccy Engine Architecture │
│ │
│ Pasteboard Observer & Filter Layer │
│ ├── `NSPasteboard.general.changeCount` Polling Loop (0.25s)│
│ ├── Password Manager Concealed Type Filter │
│ │ ├── `org.nspasteboard.ConcealedType` (1Password) │
│ │ └── `org.nspasteboard.TransientType` (Bitwarden) │
│ └── Secure Input State Detector (`IsSecureEventInputEnabled`)│
│ │
│ Storage & Search Pipeline │
│ ├── CoreData / SQLite Storage (`Storage.sqlite`) │
│ ├── Fuzzy Search Indexer (Title, Rich Text, Images) │
│ └── Pinned Items Cache (Persistent Header Entries) │
│ │
│ Paste Execution Layer │
│ ├── Direct Pasteboard Write (`NSPasteboard.clearContents`) │
│ └── Synthetic Keystroke Dispatch (`CGEvent` ⌘+V Injection) │
└─────────────────────────────────────────────────────────────┘
```
---
## Operational Capabilities & Agent Directives
1. **Pasteboard Change Polling & Type Filtering**: Implement clean Swift pasteboard monitors that filter transient/concealed types and avoid capturing sensitive credentials.
2. **Secure Input Lock Triage**: Diagnose stalled clipboard capturing by inspecting `ioreg -l -w 0 | grep SecureInput` to identify rogue processes locking macOS Secure Event Input.
3. **Synthetic Event & Accessibility Triage**: Troubleshoot auto-paste failures by verifying Maccy's Accessibility permissions (`AXIsProcessTrustedWithOptions`).
4. **CoreData Database Maintenance**: Query, vacuum, and repair corrupted Maccy SQLite databases (`~/Library/Containers/org.pavelm.Maccy/Data/Library/Application Support/Maccy/Storage.sqlite`).
---
## Production Swift Automation: Headless Pasteboard Monitor & Sensitive Data Filter
Save this script as `pasteboard_monitor.swift` and execute via `swift pasteboard_monitor.swift`:
```swift
// ==============================================================================
// Standalone Swift 5.x Script: Secure NSPasteboard Change Monitor
// Polls NSPasteboard.general, filters password manager transient types, and logs.
// ==============================================================================
import Cocoa
class SecurePasteboardMonitor {
private let pasteboard = NSPasteboard.general
private var lastChangeCount: Int
private var timer: Timer?
// Standard Concealed Pasteboard Types Used by Password Managers
private let concealedTypes: [NSPasteboard.PasteboardType] = [
NSPasteboard.PasteboardType("org.nspasteboard.ConcealedType"),
NSPasteboard.PasteboardType("org.nspasteboard.TransientType"),
NSPasteboard.PasteboardType("org.nspasteboard.AutoGeneratedType"),
NSPasteboard.PasteboardType("com.agilebits.onepassword")
]
init() {
self.lastChangeCount = pasteboard.changeCount
}
func startMonitoring() {
print("--- [MACCY SECURE PASTEBOARD MONITOR ACTIVE] ---")
timer = Timer.scheduledTimer(withTimeInterval: 0.25, repeats: true) { [weak self] _ in
self?.checkPasteboard()
}
RunLoop.current.run()
}
private func checkPasteboard() {
guard pasteboard.changeCount != lastChangeCount else { return }
lastChangeCount = pasteboard.changeCount
// 1. Check for Concealed / Password Manager Types
if let types = pasteboard.types {
for concealed in concealedTypes {
if types.contains(concealed) {
print("⚠️ IGNORED: Sensitive/Concealed password manager clip detected.")
return
}
}
}
// 2. Extract Plain Text or Rich Text
if let text = pasteboard.string(forType: .string) {
let preview = text.prefix(50).replacingOccurrences(of: "\n", with: " ")
print("📋 Captured Clip [Length: \(text.count)]: \"\(preview)...\"")
} else if let types = pasteboard.types, types.contains(.png) || types.contains(.tiff) {
print("🖼️ Captured Image Clip.")
}
}
}
let monitor = SecurePasteboardMonitor()
monitor.startMonitoring()
```
---
## Technical Troubleshooting Matrix
| Issue & Failure Signature | Root Cause Analysis | Diagnostic & Resolution Pathway |
| :--- | :--- | :--- |
| **Maccy Stops Recording New Clipboard Items** | Another application (Terminal, password manager, or game) locked macOS Secure Event Input. | 1. In Terminal, run: `ioreg -l -w 0 \| grep -i secureinput`.
2. Identify the locking process ID.
3. Close the offending application or disable Secure Keyboard Entry in Terminal settings. |
| **Selecting an Item Copies but Fails to Auto-Paste** | Maccy lacks macOS Accessibility permissions to simulate the `Command + V` keystroke. | 1. Open *System Settings $\rightarrow$ Privacy & Security $\rightarrow$ Accessibility*.
2. Remove and re-add **Maccy**.
3. Verify in Maccy Preferences $\rightarrow$ **General** $\rightarrow$ *Paste automatically* is checked. |
| **Maccy Crashes on Launch with CoreData Error** | Local SQLite database `Storage.sqlite` corrupted due to abrupt system shutdown. | 1. Navigate to `~/Library/Containers/org.pavelm.Maccy/Data/Library/Application Support/Maccy/`.
2. Backup and delete `Storage.sqlite` and `Storage.sqlite-wal`.
3. Relaunch Maccy to initialize a clean database. |
| **Global Hotkey (⌘+Shift+C) Conflicts with Other App** | Hotkey collision with another developer utility or IDE shortcut. | In Maccy Preferences $\rightarrow$ **General**, click the shortcut recorder and assign an alternative combo (e.g. `⌥ + V`). |
---
## Command Line Syntax & macOS Diagnostics
```bash
# 1. Inspect macOS Secure Input Status to Identify Locking Process
ioreg -l -w 0 | grep -i secureinput
# 2. Inspect Maccy Preferences via defaults CLI
defaults read org.pavelm.Maccy
# 3. Clear Maccy History via SQLite Database Execution
sqlite3 ~/Library/Containers/org.pavelm.Maccy/Data/Library/Application\ Support/Maccy/Storage.sqlite "DELETE FROM ZHISTORYITEM;"
```
### Essential File Locations
- **Maccy Preferences**: `~/Library/Containers/org.pavelm.Maccy/Data/Library/Preferences/org.pavelm.Maccy.plist`
- **CoreData Database**: `~/Library/Containers/org.pavelm.Maccy/Data/Library/Application Support/Maccy/Storage.sqlite`
---
## Agent Operational Directive
> **MANDATORY**: When diagnosing clipboard recording issues in Maccy, always execute `ioreg -l -w 0 | grep -i secureinput` to rule out macOS Secure Event Input locks before altering database or preference files.