If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/p0deje/Maccy shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 3mo ago
• 6 active contributors
• MIT licensed
• ⚠ Concentrated ownership — top contributor handles 51% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live p0deje/Maccy repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/p0deje/Maccy.

What it runs against: a local clone of p0deje/Maccy — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in p0deje/Maccy | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 119 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of p0deje/Maccy. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/p0deje/Maccy.git
#   cd Maccy
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of p0deje/Maccy and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "p0deje/Maccy(\\.git)?\\b" \\
  && ok "origin remote is p0deje/Maccy" \\
  || miss "origin remote is not p0deje/Maccy (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Maccy/AppDelegate.swift" \\
  && ok "Maccy/AppDelegate.swift" \\
  || miss "missing critical file: Maccy/AppDelegate.swift"
test -f "Maccy/Clipboard.swift" \\
  && ok "Maccy/Clipboard.swift" \\
  || miss "missing critical file: Maccy/Clipboard.swift"
test -f "Maccy/ApplicationImageCache.swift" \\
  && ok "Maccy/ApplicationImageCache.swift" \\
  || miss "missing critical file: Maccy/ApplicationImageCache.swift"
test -f "Maccy.xcodeproj/project.pbxproj" \\
  && ok "Maccy.xcodeproj/project.pbxproj" \\
  || miss "missing critical file: Maccy.xcodeproj/project.pbxproj"
test -f "Maccy/Assets.xcassets" \\
  && ok "Maccy/Assets.xcassets" \\
  || miss "missing critical file: Maccy/Assets.xcassets"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 119 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~89d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/p0deje/Maccy"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Maccy is a lightweight clipboard manager for macOS that maintains a searchable history of copied content and enables quick retrieval without leaving the keyboard. It monitors the system clipboard via NSPasteboard, stores items in a local database, and provides instant access through a popup UI triggered by ⇧⌘C, supporting text, images, and rich content types while maintaining zero internet connectivity. Single-target macOS app structure: Maccy.xcodeproj contains the main app bundle; Swift source code likely in a Sources/ or Maccy/ directory (not shown in top 60 files but typical); Designs/ holds Sketch and Pixelmator assets for UI mockups; .github/ISSUE_TEMPLATE/ and config files (SwiftLint, Periphery, Bartycrouch) indicate professional release automation.

macOS power users and developers who copy-paste frequently and want instant historical access to previous clipboard items without context-switching; also system administrators managing multiple machines who value a minimal, open-source alternative to paid clipboard managers.

Production-ready and actively maintained. The project has significant GitHub traction (downloads badge visible in README), builds via Bitrise CI/CD, targets macOS Sonoma 14+, uses SwiftLint for code quality, and maintains a structured issue template system. Recent activity is evident from organized design assets and ongoing localization support via Bartycrouch.

Low-to-moderate risk profile: single maintainer (p0deje) with no visible backup, but codebase is pure Swift with minimal external dependencies typical for native macOS apps. Main risk is macOS API compatibility—each major OS release (Sonoma 14+ requirement) could require refactoring. No visible test directory in file listing suggests test coverage is unknown or minimal.

Active development on localization (Bartycrouch config), design refinements (6 App Store design files with versioning), and code quality via Periphery (unused code detection) and SwiftLint. Issue templates suggest systematic triage; FUNDING.yml indicates sponsorship setup.

git clone https://github.com/p0deje/Maccy.git
cd Maccy
open Maccy.xcodeproj

Then build and run via Xcode (⌘R). No external package manager evident in file list—this is a native Xcode project.

Daily commands: Open Maccy.xcodeproj in Xcode, select the Maccy scheme, and press ⌘R to build and run. The app will install a menu bar icon; use ⇧⌘C to trigger the popup. Alternatively: brew install maccy for pre-built distribution.

• Maccy/AppDelegate.swift — Application entry point and lifecycle management; initializes core services like clipboard monitoring, menu, and hotkey handling
• Maccy/Clipboard.swift — Core clipboard monitoring and history management; handles the primary business logic of tracking clipboard changes
• Maccy/ApplicationImageCache.swift — Caches application icons for clipboard items; critical for UI performance when displaying history with icons
• Maccy.xcodeproj/project.pbxproj — Xcode project configuration; defines all build targets, dependencies, schemes, and asset configurations
• Maccy/Assets.xcassets — All application UI assets including app icon, menu bar images, and clipboard-related icons used throughout the interface
• .swiftlint.yml — Swift code style and quality standards enforced across the codebase; essential for maintaining consistent quality

• AppDelegate (Swift, AppKit, NSApplication) — Application lifecycle, status bar menu initialization, global event routing, and service coordination
  • Failure mode: If app crashes or quits, clipboard history is preserved in UserDefaults but monitoring stops until relaunch
• Clipboard Manager (Swift, NSPasteboard, DispatchSourceTimer, UserDefaults) — Monitors NSPasteboard for changes, parses content types, maintains in-memory history, and persists to UserDefaults
  • Failure mode: If polling is delayed or skipped, clipboard events may be missed; history may become inconsistent with actual clipboard
• ApplicationImageCache (Swift, NSWorkspace, LRU cache) — Caches application icons by bundle identifier using LRU eviction; provides fast lookup for menu rendering
  • Failure mode: Cache miss or invalid icon fails gracefully (falls back to generic icon); stale icons if app is updated
• Menu Renderer (Swift, AppKit, NSMenuItem) — Converts clipboard history into macOS menu items with icons, text preview, and search filtering
  • Failure mode: If menu exceeds system limits (~200 items), older items are dropped; search filtering may fail if history is corrupted
• Accessibility Integration (Swift, AXUIElement, macOS Accessibility API) — Requests and validates user accessibility permissions to determine source app of clipboard changes
  • Failure mode: If permission denied, source app detection fails; Maccy reverts to showing

Add a new clipboard data type handler

1. Extend the Clipboard.swift history storage to recognize new pasteboard types via NSPasteboard type checking (Maccy/Clipboard.swift)
2. Create a new presentation class (e.g., ColorImage.swift pattern) to render the new type in the history menu (Maccy/ColorImage.swift)
3. Add localized copy type names in the Extensions/Defaults.Keys+Names.swift file (Maccy/Extensions/Defaults.Keys+Names.swift)

Add a new UI feature to the menu

1. Add a new Swift view or menu item construction in AppDelegate.swift where the menu is initialized (Maccy/AppDelegate.swift)
2. Add corresponding UI assets (icons/images) to Assets.xcassets with both light and dark variants (Maccy/Assets.xcassets)
3. Wire menu action handlers and state observers by referencing Clipboard.swift history data (Maccy/Clipboard.swift)

Optimize performance for large clipboard histories

1. Review and extend ApplicationImageCache.swift LRU cache eviction policy and size limits (Maccy/ApplicationImageCache.swift)
2. Profile memory usage in Clipboard.swift history storage and add pagination/lazy loading if needed (Maccy/Clipboard.swift)
3. Add cache statistics and performance metrics via extensions in Extensions/ folder (Maccy/Extensions)

• Swift + AppKit — Native macOS development; direct access to NSPasteboard clipboard APIs and menu bar integration
• Timer-based polling (NSTimer/DispatchSourceTimer) — Simple, reliable clipboard change detection without requiring system-level keyboard/permission hooks; respects privacy
• UserDefaults for persistence — Lightweight, native macOS storage for clipboard history; no external database dependency
• LRU cache (ApplicationImageCache) — Bounded memory usage for application icon caching; prevents unbounded growth with large histories

• Timer-based clipboard polling instead of system-level hooks

  • Why: Simpler implementation, no complex permission handling, fewer system integration points
  • Consequence: Slight latency (typically < 100ms) between copy action and history detection; configurable poll interval trades CPU for responsiveness

• In-process menu rendering vs. separate menu daemon

  • Why: Simpler architecture, direct access to clipboard state, no IPC overhead
  • Consequence: Menu updates are synchronous and can block if clipboard operations take time; scales to ~1000 items before UI lag

• UserDefaults-only persistence vs. SQLite/database

  • Why: Minimal dependencies, zero setup, works across user sessions transparently
  • Consequence: Limited query capabilities; full history must be loaded into memory; plist serialization slower for very large histories (>5000 items)

• Application icon caching via LRU vs. always re-fetch

  • Why: Improves menu rendering performance for repeated apps
  • Consequence: Stale icon if app icon is updated; bounded memory trade-off with cache size tuning

• Does not provide cloud sync or cross-device clipboard sharing
• Does not integrate with system clipboard synchronization (iCloud, etc.)
• Does not filter or anonymize sensitive clipboard content (e.g., passwords) by default—user must configure ignore rules
• Does not support older macOS versions (requires Sonoma 14+)
• Does not provide plugin/extension system for custom clipboard handlers
• Does not support Windows or Linux

macOS-only development—no Linux or Windows CI visible; requires Apple Silicon or Intel Mac with Xcode installed. NSPasteboard access may require Accessibility permissions at runtime on Sonoma+. No Podfile or Package.swift visible suggests minimal CocoaPods/SPM usage, reducing dependency drift but increasing maintenance burden. Localization via Bartycrouch requires macOS host (uses native tools).

• NSPasteboard — Core macOS API for clipboard access; understanding pasteboard types (string, image, etc.) and change notifications is fundamental to implementing clipboard monitoring in this app
• Menu Bar Integration (NSStatusBar / NSStatusItem) — Maccy runs in the menu bar (⌘ icon in top-right); this is a macOS-specific UI pattern for always-accessible helper apps, not available on other platforms
• Hotkey Registration (Event Monitor) — Global keyboard shortcut (⇧⌘C) must be registered system-wide while the app is backgrounded; requires either event tapping or system API integration to avoid conflicts
• Accessibility Permissions (Privacy Controls) — Modern macOS requires Accessibility framework authorization for clipboard monitoring and hotkey capture; app will fail silently without Info.plist declarations and user consent
• Persistent Local Storage (Core Data / SQLite) — Clipboard history must survive app restarts; likely uses Core Data or direct SQLite for efficient storage without network dependency, critical for privacy claims
• Markdown Localization (Bartycrouch Automation) — UI strings are extracted and translated via Bartycrouch tooling; contributing text requires understanding the workflow to avoid merge conflicts in .strings files across 6+ languages
• Code Quality Static Analysis (SwiftLint / Periphery) — All commits are checked against SwiftLint rules and unused code detection; understanding these tools prevents CI failures and maintains consistency with team style

• Clipy/Clipy — Predecessor and direct competitor—also a macOS clipboard manager in Swift, can be referenced for design patterns and feature parity benchmarking
• AutoPaste/AutoPaste — Alternative clipboard manager for macOS with similar hotkey-first UX, useful for feature comparison and user preference research
• sindresorhus/LaunchAtLogin — Utility library for macOS app launch-at-login behavior, commonly paired with menu bar apps like Maccy for system integration
• mas-cli/mas — Mac App Store command-line tool; Maccy distributes via App Store (visible in Designs/App-Store), so release automation may benefit from this
• serhii-londar/open-source-mac-os-apps — Curated list of open-source macOS apps; Maccy is likely listed here, provides context on ecosystem maturity and peer projects

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for ApplicationImageCache.swift

ApplicationImageCache.swift is a critical component for caching application icons in the clipboard manager, but there's no evidence of corresponding tests in the file structure. This cache is performance-sensitive and prone to memory issues. Adding unit tests would ensure reliability across macOS versions (Sonoma 14+) and prevent regressions when modifying caching logic.

• [ ] Create Maccy/ApplicationImageCacheTests.swift with XCTest suite
• [ ] Add tests for cache hit/miss scenarios
• [ ] Add tests for memory pressure handling and cache eviction
• [ ] Add tests for concurrent access to the cache
• [ ] Update Maccy.xctestplan to include the new test class

Create GitHub Actions workflow for SwiftLint validation

The repo has .swiftlint.yml configuration file indicating code style is important, but there's no visible CI workflow enforcing it on PRs. Adding a GitHub Actions workflow would catch style violations early, maintain consistency, and reduce maintainer review burden. This is especially important for an open-source macOS project with multiple contributors.

• [ ] Create .github/workflows/swiftlint.yml GitHub Action
• [ ] Configure action to run SwiftLint on all Swift files in Maccy/ directory
• [ ] Set action to fail on warnings (strict mode) based on .swiftlint.yml rules
• [ ] Add GitHub Actions badge to README.md
• [ ] Test workflow locally with act or similar tool before merging

Add integration tests for Accessibility.swift permission handling

Accessibility.swift is critical for macOS clipboard manager functionality (requires accessibility permissions), but there are no visible tests validating permission request flows or fallback behaviors. Integration tests would ensure the app handles permission denied/granted states correctly and provide reliable user experience across different macOS Sonoma versions.

• [ ] Create Maccy/AccessibilityTests.swift with integration test cases
• [ ] Add tests for accessibility permission status checks
• [ ] Add tests for request permission flow and user cancellation
• [ ] Add tests for graceful degradation when permissions denied
• [ ] Update Maccy.xctestplan to include accessibility integration tests
• [ ] Document any required test environment setup in CONTRIBUTING.md

• Add Unit Tests for Clipboard Monitoring: The file listing shows no Tests/ directory; create XCTestCase classes for NSPasteboard integration and history filtering logic to catch regressions.
• Enhance Search UX with Regex Support: Current search is likely literal string matching; add optional regex toggling in the search view (visible in Designs/03-Search.pxd) and document in README.
• Localize Missing Strings: Bartycrouch config is present but localization completeness is unknown; audit all hardcoded English strings in the codebase and add to .strings files for the 6+ languages hinted at in Designs/06-Languages.pxd.

Maccy is a relatively well-structured Swift/macOS application with moderate security posture. The primary security concerns relate to clipboard data handling and persistence rather than traditional injection or dependency vulnerabilities. The application handles sensitive user data (clipboard history) which requires strong encryption and privacy controls. The codebase shows no obvious hardcoded secrets or dangerous patterns visible in the file structure. Main recommendations focus on implementing encryption for stored clipboard data, providing users with granular privacy controls to exclude sensitive content types, and ensuring proper accessibility permissions are configured. The application should leverage macOS's built-in security features (Keychain, Sandbox, Accessibility restrictions) to minimize exposure of clipboard contents.

• Medium · Clipboard Data Persistence Without Encryption — Maccy/ (storage implementation). Maccy stores clipboard history locally. The file structure indicates persistent storage of clipboard contents, which may include sensitive data (passwords, API keys, personal information). If the storage mechanism lacks encryption, sensitive clipboard data could be exposed if the system is compromised or the storage file is accessed. Fix: Implement encryption-at-rest for stored clipboard items using macOS Keychain or similar secure storage. Add user-configurable options to exclude sensitive types (passwords, tokens) from history. Consider implementing automatic data expiration policies.
• Medium · Potential Insecure Clipboard Access Permissions — Maccy/Accessibility.swift. The application accesses system clipboard contents which may include sensitive information from other applications. Without proper accessibility controls and user awareness, the application could be used to extract sensitive data from the clipboard history. Fix: Implement robust user consent mechanisms. Add clear UI indicators when clipboard history contains sensitive content types. Provide granular privacy controls allowing users to exclude specific applications or content types from history. Log access for audit purposes.
• Low · Missing Security Headers and Transport Security Configuration — Maccy.xcodeproj/. No visible configuration for App Transport Security (ATS) or security headers in the Xcode project configuration. This could potentially allow insecure network communications if the app performs any network operations. Fix: Ensure Info.plist includes proper ATS configuration. Enforce HTTPS-only communication. Validate all external dependencies use secure protocols.
• Low · Dependency Resolution File Exposed — Maccy.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved. Package.resolved file in the repository reveals exact dependency versions, which could be used by attackers to identify known vulnerabilities in specific versions. Fix: While Package.resolved should be tracked, ensure all dependencies are regularly updated. Implement dependency scanning in CI/CD pipeline using tools like SwiftPM's vulnerability scanning or third-party SBOM tools.
• Low · Missing Input Validation Documentation — Maccy/ (core clipboard handling). No visible validation or sanitization patterns for user input or clipboard content handling in the file structure. Risk of processing malformed or malicious clipboard data. Fix: Implement strict input validation for all clipboard content types. Define maximum size limits for stored items. Handle edge cases and malformed data gracefully without exposing errors.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.