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 mouse and keyboard macro recorder and player with macro editor, text expansion, shortcuts, and scheduling.
Linux support for Wayland and X11
Windows support (Microsoft Store, winget, portable binary)
> AppImage users: Run the quick one-time setup in AppImage Setup before first launch.
> Flatpak users (Wayland): On first launch, CrossMacro may show a Wayland Setup Required dialog and run Quick Setup for device permissions.
Linux Post-Install (Daemon Packages)
CrossMacro supports two Linux runtime modes:
Daemon-backed mode: the preferred packaged mode. The app talks to crossmacro.service
over /run/crossmacro/crossmacro.sock, while the daemon service user keeps Linux device access.
Direct device mode: an intentional fallback for channels like AppImage, and for some
Wayland/sandbox scenarios when daemon-backed mode is unavailable. In this mode the app process
itself needs access to /dev/uinput and, for recording or hotkeys, readable /dev/input/event*.
On X11, CrossMacro tries the native X11 capture and playback backends first. A supported native X11
session doesn't require the daemon or direct device fallback.
After installing daemon packages on Linux, run:
sudo usermod -aG crossmacro $USER
# Reboot or re-login for group changes
AUR, .deb, and .rpm packages try to enable/start crossmacro.service during install
on systemd hosts. If your environment skips that step (for example non-systemd/chroot),
run manually:
sudo systemctl enable --now crossmacro.service
Note: crossmacro group membership allows the client to talk to the daemon socket.
The daemon service user keeps device access separately for /dev/input/event* and /dev/uinput
(typically via input and, on some distros, uinput supplementary groups). Normal users should only need membership in crossmacro to talk to the daemon socket in daemon-backed mode.
AppImage Setup (Portable Linux)
AppImage currently uses direct device mode, not the packaged daemon-backed service path.
That means the user session itself needs the Linux input permissions described below.
If you use the AppImage build on Linux, complete this one-time setup before first launch:
# Add uinput rule
echo 'KERNEL=="uinput", GROUP="input", MODE="0660", OPTIONS+="static_node=uinput"' | sudo tee /etc/udev/rules.d/99-crossmacro.rules
# Reload udev rules
sudo udevadm control --reload-rules && sudo udevadm trigger
# Add your user to input group
sudo usermod -aG input $USER
Note: adding a user to input grants direct access to input devices.
Flatpak Wayland Setup
For Flatpak on Wayland, CrossMacro supports a hybrid startup path:
Daemon-backed mode when the host daemon socket is exposed at /run/crossmacro/crossmacro.sock
Direct device mode when the daemon path is unavailable and temporary device access is granted to the user session
If required permissions are missing, app startup shows Wayland Setup Required and can run Quick Setup automatically.
Quick Setup enables the direct device mode fallback by using flatpak-spawn --host pkexec to apply session ACLs on the host:
rw access to /dev/uinput (or /dev/input/uinput if present)
r access to /dev/input/event*
If Quick Setup is denied or fails, you can apply the same permissions manually on host:
sudo modprobe uinput
for p in /dev/uinput /dev/input/uinput; do [ -e "$p" ] && sudo setfacl -m "u:$USER:rw" "$p"; done
for p in /dev/input/event*; do [ -e "$p" ] && sudo setfacl -m "u:$USER:r" "$p"; done
If setfacl is missing, install your distro's acl package first.
In other words: packaged daemon installs prefer daemon-backed mode, while AppImage and some Flatpak/Wayland scenarios intentionally rely on direct device mode when the daemon path is unavailable.
Nix and NixOS
nix run github:alper-han/CrossMacro and nix profile install nixpkgs#crossmacro provide the UI package only.
The daemon-backed Linux model on Nix is provided by the NixOS module in flake.nix, which provisions the crossmacro.service, daemon user, group membership, and runtime directory policy.
Advanced Platform Notes
Nixpkgs (unstable)
nix profile install nixpkgs#crossmacro
Run directly from this repo flake
nix run github:alper-han/CrossMacro
Use as flake input in your own flake.nix
{
inputs.crossmacro.url = "github:alper-han/CrossMacro";
outputs = { self, crossmacro, ... }:
let
system = "x86_64-linux";
in {
packages.${system}.crossmacro = crossmacro.packages.${system}.default;
};
}
Launch and grant Accessibility permissions when prompted.
If Gatekeeper blocks first launch:
xattr -cr /Applications/CrossMacro.app
CLI Usage
crossmacro --help
crossmacro --version
crossmacro play ./demo.macro --speed 1.25 --repeat 3
crossmacro macro validate ./demo.macro
crossmacro macro info ./demo.macro
crossmacro doctor --json
crossmacro settings get
crossmacro settings get playback.speed
crossmacro settings set playback.speed 1.25
crossmacro schedule list
crossmacro schedule run
crossmacro shortcut list
crossmacro shortcut run
crossmacro record --output ./recorded.macro --duration 10
crossmacro headless
For desktop autostart, use crossmacro --start-minimized. When tray icon support is available, CrossMacro starts hidden to tray; otherwise it starts as a minimized window.
GNOME Wayland needs a shell extension for absolute mouse position.
Log out/in after first-time setup if prompted.
Wayland cursor positioning options
CrossMacro works on Wayland.
Absolute cursor position is available on:
Hyprland (IPC)
Wayfire (IPC, ipc + ipc-rules plugins, v0.10+)
Wayfire IPC discovery checks WAYFIRE_SOCKET, then XDG_RUNTIME_DIR, then temp-directory socket candidates.
KDE Plasma (D-Bus)
GNOME (Shell Extension)
If an absolute cursor provider is unavailable, CrossMacro automatically falls back to relative-position mode.
You can force relative mode with Force Relative Coordinates.
You can disable origin move at recording start with Skip Initial 0,0 Position.
For the smoothest relative-position playback, disable pointer acceleration and use a flat pointer profile in your desktop or compositor settings; accelerated profiles can distort replayed movement deltas.
Both absolute and relative modes support macro recording and playback.
Install polkit to enable daemon mode on minimal systems.
Input capture conflicts (Linux)
Some applications can lock input devices exclusively.
If capture/playback behaves inconsistently, pause conflicting tools (example: GPU Screen Recorder), test CrossMacro, then resume them.
