macOS Setup

June 23, 2026 ยท View on GitHub

CrossMacro on macOS needs the normal drag-and-drop app install flow plus macOS privacy permissions for desktop automation. Use this page when setting up the DMG build from GitHub Releases.

Install

  1. Download the matching .dmg from GitHub Releases: osx-arm64 for Apple Silicon or osx-x64 for Intel.
  2. Open the DMG.
  3. Drag CrossMacro to Applications.
  4. Launch CrossMacro from Applications.

CrossMacro DMG install window

If macOS says the app is damaged

GitHub DMG downloads can sometimes keep a quarantine flag that makes macOS show this warning:

macOS damaged app warning

If this happens after dragging the app to Applications, run:

xattr -cr /Applications/CrossMacro.app

Then open CrossMacro again from Applications.

Required permissions

CrossMacro needs two macOS privacy permissions for normal macro use:

  • Input Monitoring lets CrossMacro read keyboard and mouse input for recording and global shortcuts.
  • Accessibility lets CrossMacro play macros back by sending keyboard and mouse events.

Macros that read pixels from the screen also need Screen Recording. This is required for commands such as pixelcolor, waitcolor, and pixelsearch.

CrossMacro opens the relevant System Settings page when possible and asks macOS to add the current app to the permission list. In most cases, you only need to turn on the CrossMacro toggle and return to the app.

CrossMacro permission required dialog

Input Monitoring

When macOS asks for keystroke access, choose Open System Settings.

macOS Input Monitoring prompt for CrossMacro

In System Settings > Privacy & Security > Input Monitoring, enable CrossMacro. CrossMacro opens this page and gets the app listed when macOS allows it, so the remaining step is usually just turning the toggle on.

CrossMacro enabled in Input Monitoring

Input Monitoring covers recording, global shortcuts, and reading input. It does not by itself allow playback.

Accessibility

After Input Monitoring is approved, CrossMacro may ask for Accessibility before playback can work. Choose Open System Settings when macOS shows the Accessibility prompt.

macOS Accessibility prompt for CrossMacro

In System Settings > Privacy & Security > Accessibility, enable CrossMacro.

CrossMacro enabled in Accessibility

Accessibility covers playback and input injection. If a permission is visible as enabled but CrossMacro still reports it missing, quit and reopen CrossMacro.

Screen Recording

Screen reading commands need macOS Screen Recording permission before CrossMacro can sample pixels from the desktop. In System Settings > Privacy & Security > Screen & System Audio Recording (or Screen Recording on older macOS versions), enable CrossMacro.

If you grant Screen Recording while CrossMacro is running, quit and reopen the app before testing pixelcolor, waitcolor, or pixelsearch again.

Troubleshooting

Start with doctor when setup, recording, shortcuts, or playback do not work:

/Applications/CrossMacro.app/Contents/MacOS/CrossMacro.UI doctor --json --verbose

DMG installs do not usually add a crossmacro command to your shell PATH. If you have installed a shell alias or symlink yourself, crossmacro doctor --json --verbose is equivalent.

For bug reports, include your macOS version, CrossMacro version, install method, relevant logs, and doctor output.