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

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

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

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 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

Contributors

Thanks to everyone who contributes to CrossMacro.

Star History

License

Licensed under GPL-3.0-only. See LICENSE.

Community