CrossMacro

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

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)
• macOS support

Contents

• Features
• Screenshots
• Quick Start
• Installation
• CLI Usage
• Troubleshooting
• Contributing
• Security
• Contributors
• Star History
• License
• Community

Features

• Mouse event recording (clicks and movement)
• Keyboard event recording
• Macro playback with pause/resume
• Loop mode, repeat count, and repeat delay controls
• Playback speed control (0.1x to 10.0x)
• Macro editor with undo/redo, coordinate capture, and action reordering
• Text expansion shortcuts (for example :mail -> email@example.com)
• Shortcut-bound macro execution (keyboard key, mouse button, or key combo)
• Shortcut modes: toggle and run-while-held
• Shortcut loop controls: repeat count and repeat delay
• Scheduled task execution
• Save and load .macro files
• Optional system tray controls
• Theme support (Classic, Latte, Mocha, Dracula, Nord, Everforest, Gruvbox, Solarized, Crimson)
• Customizable global hotkeys:
  • F8 start/stop recording
  • F9 start/stop playback
  • F10 pause/resume playback
• CLI and headless workflows

Screenshots

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

Quick Start

1. Install CrossMacro.
2. Launch the app.
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 and optionally bind it to a shortcut.

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 | | | .deb | sudo apt install ./crossmacro*.deb | Download from Releases | | | .rpm | sudo dnf install ./crossmacro*.rpm | Download from Releases | | | AUR | yay -S crossmacro<br>paru -S crossmacro | Community package | | | AppImage | Releases | One-time setup required | | | nixpkgs | nix profile install nixpkgs#crossmacro | Unstable channel | | | flake | nix run github:alper-han/CrossMacro | Run from repo | | | Store | Store | Managed updates | | | winget | winget install AlperHan.CrossMacro | CLI install | | | Portable EXE | Releases | Self-contained | | | .dmg | Releases | Drag to Apps |

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)

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 needs device access for /dev/input/event* and /dev/uinput (typically via input and, on some distros, uinput groups).

AppImage Setup (Portable Linux)

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

Then reboot/re-login and run:

chmod +x CrossMacro-*.AppImage
./CrossMacro-*.AppImage

Note: adding a user to input grants direct access to input devices.

Flatpak Wayland Setup

For Flatpak on Wayland, CrossMacro supports two modes:

• Daemon mode (socket at /run/crossmacro/crossmacro.sock)
• Direct mode (device access in sandbox)

If required permissions are missing, app startup shows Wayland Setup Required and can run Quick Setup automatically. Quick Setup uses flatpak-spawn --host pkexec and applies session ACLs on 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.

Advanced Platform Notes

<details> <summary><strong>Nixpkgs (unstable)</strong></summary>

nix profile install nixpkgs#crossmacro

</details> <details> <summary><strong>Run directly from this repo flake</strong></summary>

nix run github:alper-han/CrossMacro

</details> <details> <summary><strong>Use as flake input in your own flake.nix</strong></summary>

{
  inputs.crossmacro.url = "github:alper-han/CrossMacro";

  outputs = { self, crossmacro, ... }:
  let
    system = "x86_64-linux";
  in {
    packages.${system}.crossmacro = crossmacro.packages.${system}.default;
  };
}

</details> <details> <summary><strong>NixOS module</strong></summary>

{
  inputs.crossmacro.url = "github:alper-han/CrossMacro";

  outputs = { nixpkgs, crossmacro, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        crossmacro.nixosModules.default
        ({ ... }: {
          programs.crossmacro = {
            enable = true;
            users = [ "yourusername" ];
          };
        })
      ];
    };
  };
}

</details> <details> <summary><strong>Windows notes</strong></summary>

Update an existing winget install:

winget upgrade -e --id AlperHan.CrossMacro

For Store and fresh-install options, use the Quick Install Matrix above.

</details> <details> <summary><strong>macOS notes</strong></summary>

1. Download .dmg from Releases.
2. Drag CrossMacro to Applications.
3. Launch and grant Accessibility permissions when prompted.

If Gatekeeper blocks first launch:

xattr -cr /Applications/CrossMacro.app

</details>

CLI Us