MacGuard

Anti-theft alarm app for macOS. Protects your laptop in public places by triggering a loud alarm when unauthorized access is detected.

• Menu Bar App - Runs silently in the background with custom styled dropdown
• Input Monitoring - Detects keyboard, mouse, and trackpad activity
• Sleep/Power Detection - Triggers on lid close or power disconnect
• Lid Close Alarm - Instant alarm when lid closes (requires admin, prevents sleep)
• Bluetooth Proximity - Auto-disarm when trusted device nearby; auto-arm when all devices leave
• Multiple Trusted Devices - Support up to 10 devices (Apple and non-Apple Bluetooth)
• Dynamic Menu Bar Icon - Icon reflects armed/disarmed status
• Touch ID + PIN - Secure authentication to disarm
• Configurable Alarm - Choose from 14 system sounds, custom audio files, or bundled "Don't Touch My Mac"
• Auto-Lock - Optional screen lock when armed (configurable)
• Volume Control - Adjustable alarm volume with preview

• macOS 13 Ventura or later
• Accessibility permission (for input monitoring)
• Bluetooth (for proximity detection)

1. Download the latest DMG from GitHub Releases
2. Open the DMG and drag MacGuard to Applications
3. First launch - Run xattr -cr /Applications/MacGuard.app in Terminal

MacGuard includes automatic update checking via Sparkle. Check for updates in Settings → About → "Check for Updates".

git clone https://github.com/shenglong209/MacGuard.git
cd MacGuard
swift build -c release
./scripts/create-dmg.sh 1.3.4

The DMG will be at dist/MacGuard-1.3.4.dmg

Releases are automated via GitHub Actions:

• Merge PR to main → Automatically bumps patch version and releases
• Add release:minor or release:major label to PR for respective bumps

To prevent users from needing to re-grant Accessibility permission after each update:

1. Export your Apple Development certificate:

   ./scripts/export-certificate.sh

2. Add GitHub secrets:

   • SIGNING_CERTIFICATE_P12_BASE64: The base64-encoded .p12 file
   • SIGNING_CERTIFICATE_PASSWORD: The password for the .p12 file

1. Grant Accessibility Permission

   • Open Settings from menu bar
   • Click "Grant" next to Accessibility
   • Enable MacGuard in System Preferences → Privacy & Security → Accessibility

2. Configure Trusted Devices (optional)

   • Click "Manage Devices" in Settings → Trusted Devices
   • Add up to 10 Bluetooth devices (iPhone, AirPods, Apple Watch, or paired non-Apple devices)
   • Devices will auto-disarm alarm when nearby
   • Enable "Auto-arm when devices leave" for automatic protection when all devices leave

3. Set Backup PIN

   • Click "Set PIN" in Security section
   • Enter 4-8 digit PIN

4. Configure Behavior (optional)

   • Toggle "Lock screen when armed" on/off
   • Enable "Lid close alarm" for instant alarm on lid close (requires admin password)
   • Choose alarm sound (system sounds, custom file, or bundled)
   • Adjust volume and preview with 🔊 button

5. Arm MacGuard

   • Click "Arm MacGuard" from menu bar
   • Screen locks automatically (if enabled)
   • Any input triggers 3-second countdown

6. Disarm

   • Touch ID (if available)
   • Enter PIN
   • Trusted device proximity (automatic)

┌─────────┐
│  IDLE   │  ← Disarmed, not monitoring
└────┬────┘
     │ arm
     ▼
┌─────────┐
│  ARMED  │  ← Monitoring input, sleep, power
└────┬────┘
     │ input detected
     ▼
┌─────────┐
│TRIGGERED│  ← 3-second countdown
└────┬────┘
     │ timeout
     ▼
┌─────────┐
│ALARMING │  ← Loud alarm at max volume
└─────────┘

MacGuard/
├── MacGuardApp.swift           # App entry point
├── Managers/
│   ├── AlarmStateManager.swift      # State machine
│   ├── InputMonitor.swift           # CGEventTap monitoring
│   ├── SleepMonitor.swift           # Lid close detection
│   ├── PowerMonitor.swift           # Power disconnect
│   ├── BluetoothProximityManager.swift  # RSSI scanning
│   ├── AuthManager.swift            # Touch ID + Keychain
│   ├── AlarmAudioManager.swift      # Audio playback
│   └── UpdateManager.swift          # Sparkle auto-update
├── Views/
│   ├── MenuBarView.swift            # Menu bar dropdown
│   ├── SettingsView.swift           # Settings window
│   ├── CountdownOverlayView.swift   # Fullscreen overlay
│   ├── DeviceScannerView.swift      # Bluetooth scanner
│   ├── TrustedDevicesConfigView.swift  # Device management
│   └── ActivityLogView.swift        # Event log viewer
├── Models/
│   ├── AlarmState.swift
│   ├── TrustedDevice.swift
│   └── AppSettings.swift          # User preferences
└── Resources/
    ├── AppIcon.png
    ├── MenuBarIcon.png
    └── dont-touch-my-mac.mp3      # Bundled alarm sound

Comprehensive documentation is available in the docs/ directory:

• Project Overview & PDR - Product vision, features, requirements
• Codebase Summary - Technical overview, file structure, dependencies
• Code Standards - Swift patterns, naming conventions, best practices
• System Architecture - State machine, data flow, component design
• Project Roadmap - Completed milestones, known issues, future plans
• Deployment Guide - Build instructions, release process, CI/CD

This project was developed with the assistance of:

• Claude Code - Anthropic's AI-powered coding assistant
• ClaudeKit - Skills and workflows for Claude Code

MIT License

Pull requests welcome. For major changes, please open an issue first.