The Problem

macOS users requiring granular cursor customization lack a native, maintainable solution. System cursor replacement requires manual file placement, lacks visual editing capabilities, and does not support cross-platform theme conversion (Windows .cur/.ani, Linux Xcursor, Mousecape .cape formats). Existing tools either offer static cursor sets without editor functionality or require command-line operations incompatible with daily workflow.

What This Does

MaCursor is a macOS 15+ cursor management application replacing system cursors with user-selected artwork or converted themes. The codebase splits responsibility between low-level macOS interaction and a SwiftUI frontend:

  • CursorEngine/ contains the private macOS API bridge: CGSPrivateAPI/CGSPrivateCursor.h, CGSPrivateAPI/CGSPrivateConnection.h, and CGSPrivateAPI/CGSPrivateAccessibility.h handle kernel-level cursor rendering, while MACCursorDaemon.m/MACCursorDaemon.h manage the persistent helper process and MACAutoSwitch.m implements time-based day/night theme switching.
  • MaCursor/ is the SwiftUI application shell: MaCursorApp.swift is the app entry point, CursorService.swift coordinates theme application and hotkey handling, and CursorModel.swift along with CursorLibrary.swift manage the cursor asset library and metadata.
  • themes/ holds 169 .cursor theme files alongside a README documenting the theme gallery source.
  • .github/workflows/release.yml governs the GitHub Actions CI/CD pipeline for releases.
  • scripts/build.sh provides the local build command.

How It Is Wired

Execution flows from the SwiftUI app delegate through the service layer to the daemon:

  1. Entry point: MaCursorApp.swift — the SwiftUI App struct initializes the service and window hierarchy.
  1. Cursor application: CursorService.swift calls MACCursorDaemon via a helper tool bootstrap; the daemon uses private CGS APIs (CGSPrivateCursor.h) to set the system cursor image.
  1. Theme conversion: ThemeImporter.swift and CursorFormatReaders.swift parse external formats (Windows .cur/.ani, Linux Xcursor directories, Mousecape .cape files). ThemeConversion.swift maps parsed cursors to native .cursor slots, listing each mapping in the UI via CursorThemeEditorViewModel.swift before application.
  1. Hotkey handling: RoleMapper.swift and HelperToolManager.swift manage the macursorhelper login item (referenced in entitlements CursorEngineHelper/CursorEngineHelper.entitlements), ensuring global hotkeys registered in settings remain active across user switches.
  1. Auto-switch: MACAutoSwitch.m evaluates the system time against user-configured start times and switches the active theme via the daemon API.

The daemon carries the widest blast radius — any change to CGSPrivateAPI/ affects cursor rendering system-wide, and the private API headers have no public alternative, coupling the application to macOS version compatibility risks.

How To Use It

Setup: Download the latest .dmg from the Releases page, open the disk image, and drag MaCursor to the Applications folder. The app requires macOS 15 Sequoia or later.

Configuration: On first launch, grant accessibility permissions in System Settings → Privacy & Security → MaCursor. Configure global hotkeys, day/night switch times, and cursor scale (0.50×–4.00×, 0.1× steps) via Settings Views.swift.

Running it: Launch MaCursor from the Applications folder. To apply a theme, double-click any .cursor file from the Theme Gallery or drag a .cur/.ani/.gif file onto the editor. To convert a Windows or Linux theme, use ThemeConversionReviewView.swift to review mapped cursors before committing to the library.

Real-World Use

A user maintains a light cursor theme for daytime work and a high-contrast dark theme for evening sessions. They configure MACAutoSwitch.m to trigger the dark theme at 6 PM, and assign Cmd+Option+1 as a global hotkey via ShortcutSettingsView.swift to instantly switch to a favorite “focus” cursor without leaving any application. When a new Windows .ani animation is acquired, they drop the folder onto the importer, review the sprite-sheet composition in the preview strip, and apply the converted theme to the library in a single session.

Code Health & Issues

  • Medium/SDLC — No test files detected across the repository (292 files); untested code paths exist in MACCursorDaemon.m, MACAutoSwitch.m, and the theme conversion pipelines. Static analysis has not identified additional issues beyond this gap.
  • The repository includes a LICENSE file (GPL-3.0) and CODE_OF_CONDUCT.md, PRIVACY.md, SECURITY.md documentation files.
  • CI/CD is configured via .github/workflows/release.yml but no local test target is present in the Xcode project structure.

The Bottom Line

MaCursor delivers a capable, visually rich cursor editor for macOS 15+ with genuine cross-platform conversion workflows and a functional day/night auto-switcher. The private CGS API bridge is the architectural constraint — it enables the functionality but ties the project to macOS version stability risks and precludes sandboxing. The absence of tests and the heavy reliance on undocumented internal APIs mean production deployment would require a fork with public API shims or acceptance of version-coupled releases. Teams needing cursor customization on macOS with an editing workflow will find this the most complete available option; those requiring long-term stability or cross-platform compatibility should evaluate the maintenance burden of the private API layer.