CrossMacro is a cross-platform macro application designed to facilitate the recording and playback of keyboard and mouse actions across Linux, Windows, and macOS. It offers robust features including text expansion for quick insertions, customizable shortcuts for instant macro execution, scheduling capabilities to automate tasks at specific times, playback controls with adjustable speed settings, and system tray integration for seamless management.
Ideal for power users and developers seeking to optimize repetitive workflows, CrossMacro enhances productivity by enabling the automation of complex sequences of actions. Its support across multiple platforms ensures flexibility, while its intuitive design makes it accessible for a wide range of users looking to streamline their computing tasks efficiently.
Installation on Windows can be conveniently handled via winget, with additional options available for other platforms.
README
CrossMacro
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
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
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.
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.
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.
