Maccy

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:

// ==============================================================================
// 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

Command Line Syntax & macOS Diagnostics

# 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.