# CrossMacro

> Free, open-source mouse and keyboard macro recorder for Linux Wayland/X11, Windows, and macOS. Record, edit, replay, and schedule desktop tasks.

CrossMacro is a desktop application licensed under GPL-3.0. It records mouse and keyboard actions, provides a visual macro editor, and supports replay, hotkeys, scheduling, text expansion, a CLI, and a local MCP server. It is available for Linux, Windows, and macOS.

## Product and installation

- [Official website](https://alper-han.github.io/CrossMacro/): Overview, screenshots, platform downloads, and first-macro steps.
- [Source repository](https://github.com/alper-han/CrossMacro): README, source, license, and issue tracker.
- [Latest release](https://github.com/alper-han/CrossMacro/releases/latest): Platform-specific downloads and checksums.
- [Documentation](https://github.com/alper-han/CrossMacro/tree/dev/docs): Maintained platform setup, troubleshooting, CLI, and MCP references.

## Practical guides

- [Linux & Wayland macros](https://alper-han.github.io/CrossMacro/guides/linux-wayland-macro-recorder/): Set up CrossMacro on Linux Wayland or X11, record your first mouse and keyboard macro, and understand package permissions and compositor limits.
- [Text expansion](https://alper-han.github.io/CrossMacro/guides/text-expansion/): Use CrossMacro as a text expander on Linux, Windows, and macOS. Create text shortcuts, enable expansion, and choose paste or direct typing.
- [Scheduled desktop automation](https://alper-han.github.io/CrossMacro/guides/schedule-macros/): Schedule mouse and keyboard macros with CrossMacro: one-time tasks, intervals, and weekly routines, with active-session requirements and safe examples.

## Platform and integration references

- [Linux setup](https://github.com/alper-han/CrossMacro/blob/dev/docs/linux.md): Wayland/X11 input paths, package differences, permissions, and compositor capabilities.
- [Windows setup](https://github.com/alper-han/CrossMacro/blob/dev/docs/windows.md): Microsoft Store, portable builds, and desktop-session requirements.
- [macOS setup](https://github.com/alper-han/CrossMacro/blob/dev/docs/macos.md): macOS 14+, Intel/Apple Silicon, unsigned DMG setup, and privacy permissions.
- [CLI reference](https://github.com/alper-han/CrossMacro/blob/dev/docs/cli.md): Commands, dry runs, workflow syntax, JSON output, and runtime behavior.
- [MCP reference](https://github.com/alper-han/CrossMacro/blob/dev/docs/mcp.md): Local stdio server, trusted hosts, access policies, and restricted mode.

## Important limits

- Desktop input automation needs an active desktop session. GUI-less mode is not a display-less server mode.
- Wayland capabilities and setup vary by compositor and package. Input, cursor position, screen capture, and window control are separate capabilities.
- Text expansion needs global and per-entry enablement. Typed triggers match immediately and are case-sensitive.
- Scheduled tasks need a running GUI or GUI-less desktop runtime. The Linux input daemon alone does not run schedules.
- macOS builds are unsigned and not notarized. Required privacy permissions depend on the action.
- MCP and macros can cause real input and other side effects. Use trusted workflows and the documented policies.
- The same macro file may need changes for another application's layout, operating system, or display configuration.

## Discovery

- [Sitemap](https://alper-han.github.io/CrossMacro/sitemap.xml): Canonical indexable website pages.

This file is a concise navigation aid. The linked documentation contains the detailed behavior and limitations; this summary does not replace it.