KeymouseGo: Record and Replay Mouse and Keyboard Input in Python

What KeymouseGo Records and Who It Is For

KeymouseGo is a desktop recorder and replayer. The README describes it as a minimal, portable version of the Chinese automation tool commonly known as 按键精灵: you perform a task once, the tool captures the mouse clicks and key presses, and it repeats them as many times as you ask. The intended user is someone with a short, monotonous, purely mechanical sequence, form entry, repeated menu navigation, a fixed set of clicks in an application that offers no scripting interface of its own.

The project is written in Python and ships both as source and as a packaged executable. The README states that users without Python installed can download a release build and run the KeymouseGo binary directly. That packaging decision matters more than it looks: it means the practical audience is not only developers. Anyone who can download a file and press a button can use it.

What it is not is a scripting environment for decisions. There is no condition, no branch, no loop counter exposed in the script format, and no image recognition. The automation is a timed replay of input events. If your task requires the program to look at the screen and choose what to do next, this is the wrong category of tool.

How the Recorder Turns Actions into a JSON5 Script

The mechanism is straightforward and visible in the repository layout. The Recorder directory handles capture, the Event directory defines event types, and the GUI in UIView.py drives the workflow. Recording captures mouse clicks and keyboard actions. The README is explicit that mouse movement trajectories are not recorded, only clicks and key events. That is a deliberate reduction: a script stays short and readable, but it also means any task that depends on how the pointer travelled, hover menus with timing sensitivity, for example, is not captured faithfully.

Each recording produces a new file under the scripts directory. Those files are JSON5, and the README documents the shape: a top-level scripts array whose innermost objects are events. Each event carries a type, an event_type of EM for mouse, EK for keyboard or EX for text input, a delay in milliseconds, an action_type, and an action payload.

Coordinates are stored as percentages of the screen, not absolute pixels, which is the design choice that makes scripts portable across resolutions in principle. A coordinate of [-1, -1] means the action happens wherever the pointer currently is. Keyboard events carry a numeric code, the key character and a modifier value, as in [70, 'F', 0] for the F key.

The delay is a wait before the event, not a duration. Execution is therefore a sequential walk through the array, sleeping and dispatching. Because the README notes that the program's own speed is a limiting factor, a script that assumes a very fast input rate may not reproduce the timing you recorded.

Installing KeymouseGo and Running a First Script

The fastest path is the release build. The README says users without Python can download a release and click the KeymouseGo executable to run it. If you want to build from source, the README gives the dependency step, installing from requirements-windows.txt on Windows and requirements-universal.txt elsewhere.

# Windows
pip install -r requirements-windows.txt

# Linux / macOS
pip3 install -r requirements-universal.txt

Packaging into a single executable uses PyInstaller. The README lists a separate command per platform, and the Linux commands differ for X11 and Wayland because different pynput backends must be bundled.

# Windows
pyinstaller -F -w --add-data "./assets;assets" KeymouseGo.py

# Linux X11
pyinstaller -F -w --add-data "./assets:assets" --hidden-import "pynput.keyboard._xorg" --hidden-import "pynput.mouse._xorg" KeymouseGo.py

The README states the finished executable lands in the dist folder. For a first real run, use the desktop mode it documents: press the record button, perform your actions, press the stop button, then press start to replay. The default start hotkey is F6 and the default stop hotkey is F9. A repetition count of 0 means loop forever, which is worth remembering before you walk away from the machine.

The command line mode takes a script path directly, and the README shows both the short and long form of the repeat flag.

./KeymouseGo scripts/0314_1452.txt -rt 3
./KeymouseGo scripts/0314_1452.txt --runtimes 3

Because the scripts are plain text, you can open one and hand-edit delays or delete events. That is the practical way to fix a replay that moves too fast for the target application.

Coordinate Percentages, Resolution and the Mouse Speed Ceiling

The percentage coordinate system is the most interesting part of the design and the most likely source of quiet failure. A recorded click at 0.05208 horizontal and 0.1852 vertical means roughly 100 of 1920 pixels and 200 of 1080, as the README's worked example states for a 1920 by 1080 screen. Replay multiplies those fractions back into pixels.

That works when the display geometry is the same or proportional. It breaks when it is not. A script recorded with a taskbar, a side panel, or a window at a fixed pixel width will land somewhere else on a different monitor arrangement, because the target is expressed relative to the whole screen rather than to the window. Nothing in the format anchors an event to an application window. This is not a bug so much as the boundary of what a coordinate-based recorder can promise, and the README does not document any window-relative mode.

The second constraint is speed. The README states that when the input mouse speed exceeds a certain value, the script cannot execute at the expected input speed because the program itself is speed limited. In practice this means a recording made with fast flick gestures may replay as a slower, differently timed sequence. For applications that tolerate slow input this is invisible. For applications that time out or reorder events under slow input, it is not.

The README also notes that in some system environments the mouse events may not be captured completely, and suggests running the tool as administrator or root. That is a real operational cost on locked-down machines, and it is a hint that the capture layer sits close to the platform's input hooks rather than above them.

Platform Reality: Wayland, macOS Permissions and Linux Backends

Cross-platform support here is genuine but uneven, and the README is honest about it. On macOS, the program must be in the accessibility whitelist. If you run the packaged executable rather than the source, the terminal that launched it must also be whitelisted. The README also mentions a crash workaround involving write permissions on the ~/.qt_material directory.

chmod -R 770 ~/.qt_material

On Linux, the build instructions split X11 from Wayland, and the PyInstaller commands pull in different pynput backends, _xorg for X11 and _uinput for Wayland. The README points users who still have capture or replay problems after running as root to pynput's own limitations page. That reference is the honest part of the documentation: the project inherits its platform constraints from the input library underneath it rather than solving them.

For anyone evaluating this for a fleet of machines, the practical reading is that a script recorded on one Linux desktop may need a different build and possibly different permissions on another. The README does not document a headless mode, a service mode, or any scheduling mechanism, so unattended operation means leaving the GUI running or invoking the CLI from your own scheduler.

KeymouseGo Compared with AutoHotkey

AutoHotkey is the obvious alternative for Windows users, and the difference is categorical rather than incremental. AutoHotkey is a scripting language: you write a script that declares hotkeys, sends synthetic input, reads window titles, and branches on conditions. KeymouseGo is a recorder: you produce a script by performing the actions, and the resulting file is a list of timed events.

That means AutoHotkey can express things KeymouseGo's format cannot, such as "if this window is focused, send this key, otherwise do nothing." It also means AutoHotkey requires you to write and debug code, while KeymouseGo requires you to perform the task once correctly. For a five-click sequence you run twice a week, recording is faster than writing. For anything with a decision in it, recording is not an option at all.

The second difference is reach. AutoHotkey is a Windows tool. KeymouseGo's README documents Windows, Linux and macOS, with separate packaging instructions for each. If your machines are not all Windows, that changes the comparison. If they are, and your task has any conditional structure, AutoHotkey is the better fit and KeymouseGo will frustrate you.

A third option worth naming is writing the automation yourself with pynput, the same library KeymouseGo builds on, or with a GUI automation library that locates elements rather than coordinates. That route costs development time but removes the resolution dependency entirely.

Licence, Maintenance and What Upgrades Cost You

KeymouseGo is licensed under GPL-2.0. For an end user running the release build on a personal machine, that is unremarkable. For anyone embedding the code in a product, the copyleft terms are the thing to read carefully, and the LICENSE file in the repository root is the authoritative text. Nothing here is legal advice; if you plan to redistribute a modified build, get your own reading of GPL-2.0.

The repository is not archived, and the last push was on 2026-06-07. The release history shows v5.2 in March 2025, v5.2.1 in April 2025, and a longer gap back to v5.1.1 in February 2023. So the project has a history of quiet periods punctuated by releases, and the README points contributors at a dev branch for work in progress.

Upgrade cost is low in one sense and non-zero in another. Script files are plain JSON5 with a documented event shape, so a new release is unlikely to invalidate the scripts you already have. But the packaging commands in the README are tied to specific platforms and hidden imports, and those change when the underlying pynput or PyInstaller behaviour changes. If you build from source, budget time for re-verifying the PyInstaller command rather than assuming the one in the README still produces a working binary on your distribution.

Editorial conclusion

KeymouseGo fits anyone who repeats the same short desktop sequence on one machine at one resolution: install the release build, record once, then replay with the F6 hotkey. Skip it if your task needs screenshots, element lookup or conditional logic, because the script format holds only timed input events. Before adopting it, verify two things on your own machine: that the recorded coordinates still land correctly at your display resolution, and that recording works under Wayland or macOS accessibility permissions, since the README flags both as environment-dependent.

Frequently asked questions

Official sources

1. License: GPL-2.0
2. Project website
3. README
4. Releases
5. taojy123/KeymouseGo on GitHub