CrossMacro

June 12, 2026 · View on GitHub

CrossMacro recording interface preview

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

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

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

Text expansion shortcuts with per-entry enable/disable 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, 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

Install CrossMacro for your platform.
Launch the app and grant any platform permissions it requests.
Press F8 to start/stop recording.
Press F9 to start/stop playback.
Press F10 to pause/resume playback.
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

Channel	Command / Link	Notes
Flathub	Store `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` `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 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, and Accessibility setup: docs/macos.md

CLI Usage

Use the platform app executable as crossmacro when your install channel places it on PATH. Portable builds may require running the executable directly from its download folder.

crossmacro --help
crossmacro --version
crossmacro --start-minimized

crossmacro play ./demo.macro --speed 1.25 --repeat 3 --repeat-delay-ms 500
crossmacro macro validate ./demo.macro
crossmacro macro info ./demo.macro
crossmacro doctor --json --verbose

crossmacro settings get
crossmacro settings get playback.speed
crossmacro settings set playback.speed 1.25

crossmacro schedule list
crossmacro shortcut list
crossmacro run --step "move abs 800 400" --step "click left" --dry-run

For command syntax, direct-run steps, log levels, and GUI-less desktop runtime notes, see docs/cli.md. The headless commands still require a desktop session; they are not intended for display-less server automation.

Diagnostics and Troubleshooting

Start with doctor instead of guessing from manual commands:

crossmacro doctor --json --verbose

On Linux, doctor reports daemon-backed readiness separately from direct device readiness. Direct input checks can pass while daemon IPC still warns or fails, for example when /run/crossmacro/crossmacro.sock exists but the current login session has not picked up crossmacro group membership. Direct device readiness does not grant access to the daemon socket.

When opening an issue, include your platform, install channel, relevant logs, and crossmacro doctor --json --verbose output.

Linux setup and troubleshooting details are in docs/linux.md. For Windows or macOS capture/playback issues, restart CrossMacro after changing permissions or switching sessions, and pause other automation, overlay, or security tools before retesting.

Support and Project Links

Contribution guide: CONTRIBUTING.md
Security policy: SECURITY.md
Linux setup and troubleshooting: docs/linux.md
CLI usage and run syntax: docs/cli.md
Issues: https://github.com/alper-han/CrossMacro/issues
Discussions: https://github.com/alper-han/CrossMacro/discussions
Private vulnerability reporting: https://github.com/alper-han/CrossMacro/security/advisories/new
Packaged CLI manpage: docs/man/crossmacro.1