CrossMacro

<p align="center"> <img src="screenshots/recording-tab.png" alt="CrossMacro recording interface preview" /> </p>

CrossMacro is a cross-platform desktop automation app for recording, editing, scheduling, and replaying mouse/keyboard workflows. It combines a polished Avalonia GUI, scriptable CLI, text expansion, shortcuts, and a GUI-less desktop runtime in one app.

• Linux-first support for Wayland and X11, with daemon-backed/direct-device input modes and compositor-aware cursor positioning
• Windows support through Microsoft Store, winget, MSIX, and portable binaries
• macOS support through Apple Silicon and Intel DMG packages

Contents

• Features
• Why CrossMacro?
• Screenshots
• Quick Start
• Installation
• CLI Usage
• Diagnostics and Troubleshooting
• Support and Project Links
• Contributors
• Star History
• License
• Community

Features

Record and replay

• Mouse recording for clicks, movement, and scrolling
• Keyboard recording and macro playback with pause/resume
• Playback speed control from 0.1x to 10.0x
• Loop mode, repeat count, fixed repeat delay, and randomized repeat-delay ranges
• Customizable global hotkeys:
  • F8 start/stop recording
  • F9 start/stop playback
  • F10 pause/resume playback

Edit and organize

• Files tab for loading, saving, sequencing, and replaying .macro files
• Macro editor with undo/redo, coordinate capture, action reordering, filtering, variables, loops, conditionals, text input, and delay editing
• Screen-reading commands (pixelcolor, waitcolor, pixelsearch) for color-based automation

Automate and trigger

• Shortcut-bound macro execution with keyboard shortcuts and key combinations
• Shortcut modes for press-to-start/stop and run-while-held playback
• Scheduled task execution with interval, random interval, one-time, weekly, and custom weekday options
• CLI playback, recording, validation, settings, schedules, shortcuts, and inline run steps
• GUI-less desktop runtime for hotkeys, scheduler, shortcuts, and text expansion

Text expansion and desktop polish

• Profile management to easily save, load, and switch between different configuration setups
• Text expansion shortcuts with per-entry enable/disable, direct typing method selection, and insertion-mode controls
• Optional system tray controls where the desktop session supports tray icons
• Theme support: Classic, Latte, Mocha, Dracula, Nord, Everforest, Gruvbox, Solarized, Crimson
• Language selection, runtime log-level control, and update-check settings

Some features require platform permissions, such as Linux input device or daemon access, macOS Input Monitoring, Accessibility, Screen Recording, or desktop-session tray support.

Why CrossMacro?

CrossMacro is built for people who want desktop automation without stitching together separate recorders, hotkey tools, text expanders, and platform-specific scripts.

• One workflow across platforms: a polished Avalonia GUI with packaged builds for Linux, Windows, and macOS.
• Modern Linux support: Wayland and X11 are first-class targets, with daemon-backed/direct-device input paths and compositor-aware cursor positioning where the desktop exposes it.
• GUI when you want it, CLI when you need it: record and edit visually, run macros from scripts, or keep automation available with a GUI-less desktop runtime.
• More than playback: shortcuts, schedules, text expansion, files, themes, and editor tools live in the same app.

Screenshots

| Playback | Text Expansion | Shortcuts | | :---: | :---: | :---: | | | | | | Scheduled Tasks | Editor | Settings | | | | |

Quick Start

1. Install CrossMacro for your platform.
2. Launch the app and grant any platform permissions it requests.
3. Press F8 to start/stop recording.
4. Press F9 to start/stop playback.
5. Press F10 to pause/resume playback.
6. Save your macro, edit it if needed, and optionally bind it to a shortcut or schedule.

If setup or playback does not work, run:

crossmacro doctor --json --verbose

Installation

Download page for all release binaries:

• GitHub Releases

Quick Install Matrix

| Platform | Channel | Command / Link | Notes | | --- | --- | --- | --- | | | Flathub | Store<br>flatpak install flathub io.github.alper_han.crossmacro | Sandboxed install; daemon or Quick Setup on Wayland | | | .deb | sudo apt install ./crossmacro*.deb | Daemon-backed Linux package | | | .rpm | sudo dnf install ./crossmacro*.rpm | Daemon-backed Linux package | | | AUR | yay -S crossmacro<br>paru -S crossmacro | Community daemon-backed package | | | AppImage | Releases | Portable x86_64 and aarch64; Quick Setup may prompt on Wayland | | | nixpkgs module | services.crossmacro = { enable = true; users = [ "you" ]; }; | Daemon-backed setup with service, uinput, polkit, group, and users | | | Store | Store | Managed updates | | | winget | winget install AlperHan.CrossMacro | Stable updates may lag behind GitHub Releases | | | MSIX | Releases | App package for x64 and arm64 | | | Portable EXE | Releases | Self-contained x64 and arm64 binaries | | | .dmg | Releases | Choose osx-arm64 for Apple Silicon or osx-x64 for Intel |

First-run notes

• Linux daemon packages (.deb, .rpm, AUR): package scripts try to set up crossmacro.service and the crossmacro group. Log out and back in, or reboot, if your user was added to that group.
• Flatpak/AppImage on Wayland: CrossMacro may show a setup dialog and run Quick Setup for temporary direct device permissions.
• NixOS: use the nixpkgs module for a complete daemon-backed setup. Enable services.crossmacro and set services.crossmacro.users for your desktop users.
• Windows: Store and winget are the easiest update paths. Portable EXE users run the downloaded binary directly unless they add it to PATH.
• macOS: requires macOS 10.15 or newer. Grant Input Monitoring, Accessibility, and Screen Recording permissions when prompted; if macOS blocks a GitHub DMG on first launch after dragging the app to Applications, run xattr -cr /Applications/CrossMacro.app.

Platform-specific setup

• Linux setup, runtime modes, Wayland notes, NixOS, and daemon/direct-device troubleshooting: docs/linux.md
• Windows Store and winget provide managed updates. GitHub Releases include MSIX packages and self-contained portable EXE files for x64 and arm64.
• macOS install, Gatekeeper, Input Monitoring, Accessibility, and Screen Recording setup: docs/macos.md

CLI Usage

Use the platform app executable as crossmacro when your install channel places it