CrossMacro Alper Han

Use this command to install CrossMacro:

winget install --id=AlperHan.CrossMacro -e

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.

CrossMacro

A modern mouse and keyboard macro recording and playback application for Linux (Wayland and X11), Windows, and macOS.

Screenshots

Recording	Playback	Text Expansion

Shortcuts	Scheduled Tasks	Settings

🖥️ Supported Platforms

Full Support (Absolute Positioning)

Linux
- Hyprland (Wayland) ✓
- KDE Plasma (Wayland & X11) ✓
- GNOME (Wayland & X11) ✓
- X11 (All other desktop environments) ✓
Windows ✓
macOS ✓

Partial Support (Relative Positioning)

Linux
- Other Wayland compositors (fallback mode)

What is the difference?

Relative positioning works flawlessly for reproducing input. However, in Fallback Mode, the cursor must reset to the top-left corner (0,0) at the start of every recording and playback session.

This is required because standard Wayland security protocols prevent applications from reading the current mouse position on these compositors, so the app must force a known reference point (0,0) to calculate relative movements correctly.

🎯 Features

Mouse Event Recording: Record mouse clicks and movements
Keyboard Event Recording: Record keyboard key presses
Text Expansion: Create text shortcuts for quick insertions (e.g. :mail -> email@example.com)
Shortcuts: Assign macros to keyboard keys, mouse buttons, or combinations for instant execution
Scheduling: Run macros automatically at specific times or intervals
Macro Editor: Powerful built-in editor with undo/redo, smart coordinate capture, and action reordering to fine-tune your macros
Playback: Replay recorded macros with pause/resume support
Loop Mode: Continuously repeat macros with customizable repeat count and delay
Speed Control: Adjust playback speed from 0.1x to 10.0x
File Operations: Save/load macros in .macro format (you choose where to save)
Themes: Customize the look with Classic, Latte, Mocha, Dracula, and Nord themes
System Tray Icon: Minimize to tray and control macros from system tray (optional)
Global Hotkeys: Customizable global hotkey support
- F8: Start/Stop recording
- F9: Start/Stop playback
- F10: Pause/Resume playback

📥 Installation

Debian / Ubuntu (.deb)

# Download from GitHub Releases, then:
sudo apt install ./crossmacro-*_amd64.deb

# Add yourself to the crossmacro group (required for daemon communication)
sudo usermod -aG crossmacro $USER


# Enable and start the background service (important for daemon functionality)
sudo systemctl enable --now crossmacro.service

# Reboot your system for group changes to take effect, then start the app

Fedora / RHEL (.rpm)

# Download from GitHub Releases, then:
sudo dnf install ./crossmacro-*.x86_64.rpm

# Add yourself to the crossmacro group (required for daemon communication)
sudo usermod -aG crossmacro $USER


# Enable and start the background service (important for daemon functionality)
sudo systemctl enable --now crossmacro.service

# Reboot your system for group changes to take effect, then start the app

Arch Linux

Available on the AUR:

# Using yay
yay -S crossmacro

# Using paru
paru -S crossmacro

# Enable and start the background service (important for daemon functionality)
sudo systemctl enable --now crossmacro.service

# After installation, add yourself to the group
sudo usermod -aG crossmacro $USER

# Reboot your system for group changes to take effect, then start the app

NixOS

Run directly:

nix run github:alper-han/CrossMacro

> Note: nix run does not install the background daemon. For it to work, you must manually configure permissions (add yourself to input group and set up udev rules) as described in the AppImage section below.

Add to your configuration:

Add this to your flake.nix inputs:

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

Then in your NixOS configuration:

{ inputs, ... }: {
  imports = [ inputs.crossmacro.nixosModules.default ];
  
  programs.crossmacro = {
    enable = true;
    users = [ "yourusername" ];  # Add users who should access CrossMacro
  };
}

> Note: The NixOS module automatically sets up the daemon service, user, groups, and adds specified users to the crossmacro group.

AppImage (Portable)

This method allows you to run the app without installing anything extra. Since AppImages run on FUSE, we recommend configuring User Group Permissions for the best experience.

> ⚠️ Security Warning: Adding your user to the input group grants your user account direct access to all input devices (keystrokes, mouse moves). This bypasses the secure daemon isolation typically recommended for Linux/Wayland, but is required for the AppImage to function without a system service.

Setup Instructions (Required) 🛠️ This allows you to run the app normally (just double-click) without needing sudo.

One-time setup (Run in terminal):

# Add udev rule for uinput access
echo 'KERNEL=="uinput", GROUP="input", MODE="0660", OPTIONS+="static_node=uinput"' | sudo tee /etc/udev/rules.d/99-crossmacro.rules

# Reload rules
sudo udevadm control --reload-rules &amp;&amp; sudo udevadm trigger

# Add your user to input group
sudo usermod -aG input $USER

Restart your computer (Important for group changes to take effect).

Run the App:

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

Windows

Download the .exe file from GitHub Releases and run it directly.

Alternative (Winget):

winget install -e --id AlperHan.CrossMacro

> Note: No installation required. The executable is self-contained and doesn't require .NET to be installed.

macOS

Download the .dmg file from GitHub Releases.

Open the .dmg file.
Drag CrossMacro to your Applications folder.
Keep the app open in Applications folder. (Double check security settings if it doesn't open).

> Note: Requires Accessibility Permissions to record and play macros. You will be prompted to grant these permissions on first run.

> ⚠️ "App is damaged" Error: > If macOS prevents opening the app, run this command in Terminal to bypass Gatekeeper quarantine: > bash > xattr -cr /Applications/CrossMacro.app >

Manual Build (Development)

Requirements: .NET 10 SDK

# Clone the repository
git clone https://github.com/alper-han/CrossMacro.git
cd CrossMacro

# Install daemon (Linux only)
sudo ./scripts/daemon/install.sh

# Run the application
dotnet run --project src/CrossMacro.UI/

⚙️ How It Works

Linux (Wayland)

CrossMacro uses a secure daemon architecture on Wayland:

┌─────────────────┐     IPC Socket      ┌──────────────────────┐
│  CrossMacro UI  │ ◄─────────────────► │  CrossMacro Daemon   │
│  (Your User)    │                     │  (System Service)    │
└─────────────────┘                     └──────────────────────┘
                                               │
                                               ▼
                                        /dev/input/* (read)
                                        /dev/uinput  (write)

Daemon runs as a system service with input group privileges
UI runs as your normal user, communicates via Unix socket
Security: Wayland's strict security model prevents direct input access, so a privileged daemon handles input capture/simulation
Position: Mouse position is obtained via compositor-specific protocols (Hyprland IPC, KDE D-Bus, GNOME Shell Extension)

Linux (X11)

CrossMacro uses native X11 APIs for direct input handling on X11:

┌─────────────────────────────────────┐
│         CrossMacro UI               │
│  (Single Process Architecture)      │
└─────────────────────────────────────┘
              │
              ▼
       X11 Server (Xlib)
       ├─ XTest Extension (simulation)
       │  ├─ XTestFakeKeyEvent()
       │  ├─ XTestFakeButtonEvent()
       │  └─ XTestFakeMotionEvent()
       │
       └─ XInput2 Extension (capture)
          ├─ XI_RawKeyPress/Release
          ├─ XI_RawButtonPress/Release
          └─ XI_RawMotion

Single Process: No separate daemon required (but daemon is still supported for unified experience)
XTest: Simulates keyboard, mouse, and scroll events directly to X server
XInput2: Captures raw input events from all master devices
Position: XQueryPointer() provides accurate cursor position
Permissions: Runs with normal user privileges through X protocol

Windows

CrossMacro uses Windows API hooks for input handling:

┌─────────────────────────────────────┐
│         CrossMacro UI               │
│  (Single Process Architecture)      │
└─────────────────────────────────────┘
              │
              ▼
    Windows API (User32.dll)
    ├─ SendInput()      (simulation)
    └─ SetWindowsHookEx() (capture)

Single Process: No separate daemon required
API Hooks: Uses low-level keyboard and mouse hooks
Permissions: Runs with normal user privileges

macOS

CrossMacro uses CGEvent Taps (Core Graphics) for input handling:

┌─────────────────┐
│  CrossMacro UI  │
└─────────────────┘
        │
        ▼
   Core Graphics (CGEvent)
   ├─ CGEventCreate()     (simulation)
   └─ CGEventTapCreate()  (capture)

Native Integration: Uses native macOS APIs for high performance.
Permissions: Requires Accessibility API access (System Settings > Privacy & Security > Accessibility).

🛠️ Troubleshooting

GNOME: Extension Required

CrossMacro requires a GNOME Shell extension to read mouse position on Wayland. The extension is automatically installed and enabled when you first run CrossMacro.

> Note: You need to log out and log back in for the extension to take effect after the first installation.

> Note: When using AppImage (without the system daemon), this extension is still required for recording mouse positions. The app will handle input simulation directly via the permissions granted.

CrossMacro will show a warning if the extension is not active.

Daemon Not Running

Check daemon status:

systemctl status crossmacro.service

If not running:

sudo systemctl start crossmacro.service
sudo systemctl enable crossmacro.service  # Auto-start on boot

Permission Denied Errors

Ensure you're in the crossmacro group:

groups | grep crossmacro

If not, add yourself:

sudo usermod -aG crossmacro $USER
# Reboot your system for group changes to take effect!

Polkit Not Available (Minimal/Embedded Systems)

The daemon requires polkit for authorization. If your system doesn't have polkit installed (some minimal or embedded distributions), the daemon will reject all connections.

Check if polkit is installed:

which pkcheck
# or
pkcheck --version

If polkit is not available:

The daemon won't work without polkit
Use the AppImage instead with input group permissions (see AppImage section above)

> Note: Most desktop Linux distributions (Fedora, Ubuntu, Arch, etc.) include polkit by default. This is typically only an issue on minimal server installations or embedded systems.

Enable Debug Logging

To enable debug logging for troubleshooting:

sudo systemctl kill -s USR1 crossmacro
journalctl -u crossmacro -f

Send the signal again to switch back to normal logging.

Keyboard Events Not Recording (Mouse Works)

Some applications lock input devices to prevent them from being used by other programs. One such application is GPU Screen Recorder.

To temporarily stop the conflicting service and record your macros:

systemctl --user stop gpu-screen-recorder
pkill -9 -f gpu-screen-recorder

After you're done recording, you can restart the service with:

systemctl --user start gpu-screen-recorder