Maccy

---
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`.<br>2. Identify the locking process ID.<br>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*.<br>2. Remove and re-add **Maccy**.<br>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/`.<br>2. Backup and delete `Storage.sqlite` and `Storage.sqlite-wal`.<br>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.