KeymouseGo records clicks but never the cursor path
Mouse and keyboard recording and automation similar to Jianjing Jingling, simulating clicks and keystrokes | automate mouse clicks and keyboard input.
At a glance
- What is it?
- KeymouseGo is a Python desktop recorder for Windows, Linux and macOS that turns one manual pass of clicks and keystrokes into an editable json5 script and replays it. It never captures cursor movement, and its own documentation marks the edges: administrator or root rights, or accessibility permissions on macOS, and no build command for macOS.
- Who is it for?
- KeymouseGo suits someone who wants a desktop recorder for short fixed click sequences on a single machine and is willing to edit the generated json5 file afterwards. It does not suit work that needs a recorded cursor path or a macOS build from source, since no build command is given for that platform.
- Can I use it commercially?
- Yes, with conditions. GPL-2.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 161 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- taojy123/KeymouseGo10,654 ★ · +82
| Repository | 2026-09-22 | 2026-11-15 |
|---|---|---|
| taojy123/KeymouseGo | 10.6k | 10.7k |
82 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Recording keeps clicks and keystrokes and drops the cursor path
A KeymouseGo session is four steps: start the recorder, do the job once, stop the recording, press start. Each finished recording becomes a new text file under scripts, and pressing start replays that event list in order. F6 is bound to the same action as the start button in the window, and F9 halts a run already in progress.
Two gaps sit inside that loop. The recorder keeps mouse clicks and keyboard input and nothing about the movement between them, so work that depends on the pointer travelling (opening a menu by hover, dragging a slider, selecting a range) is recorded as a set of clicks with no path connecting them. On replay each click event carries its own recorded screen position, so nothing reproduces the path between clicks.
The second gap is timing. The README states that the program is speed limited, so input faster than a certain rate is not executed at the speed it was recorded. Human pacing captured during a careful pass is not a pacing guarantee on replay.
Where this differs from a hand written hotkey script is where the commands come from. The README describes the tool as a slimmed down, portable take on 按键精灵: you do the job once and the computer repeats it. The README shows a flat sequence of delayed events; the script syntax reference, including advanced features, lives in the project wiki.
A run is a json5 list of individual press and release events
The script file is json5, and the innermost object of each entry is one event. event_type is EM for mouse or EK for keyboard, delay is the wait in milliseconds before the action fires, and action_type names the individual press or release. This is the opening of the script format example:
{
scripts: [
// 开始运行 `3000ms` 后,在屏幕相对坐标 `(0.05208, 0.1852)`即 `(100,200)` 处 `按下鼠标右键`;
{type: "event", event_type: "EM", delay: 3000, action_type: "mouse right down", action: ["0.05208%", "0.1852%"]},
// 等待 `50ms` 后在相同位置 `抬起鼠标右键`;
// 横纵坐标为[-1, -1]时,表示在鼠标当前所在位置执行操作。
{type: "event", event_type: "EM", delay: 50, action_type: "mouse right up", action: [-1, -1]},
// 等待 `1000ms` 后 `按下f键`;
{type: "event", event_type: "EK", delay: 1000, action_type: "key down", action: [70, 'F', 0]},The mouse entry shows the geometry, and the demonstration screen is 1920 * 1080, where the pair (0.05208, 0.1852) resolves to (100, 200). A keyboard entry carries a three part action array instead, with 70 and 'F' recorded for the f key.
Press and release are separate events with a delay between them, never one combined click. That separation is the reason to keep the file rather than discard it: a recorded macro can be opened in an editor, one delay stretched, an extra event pasted in, then replayed without re-recording the sequence.
Screen fractions outlive the display a script was recorded on
Because coordinates are stored as a share of the screen, the same file means something different on a different panel. A click recorded a tenth of the way across a 1920 * 1080 display is not a tenth of the way across a laptop: the fraction holds, the pixel does not. Moving a macro between machines, or replaying one after a resolution change, means re-checking every event by hand.
The [-1, -1] pair is the escape hatch, since those coordinates mean perform the action wherever the cursor happens to be. It is what keeps a script valid across machines, at the price of depending on where the previous event landed.
How a recording behaves on a second monitor, or when the display geometry changes between recording and replay, is not documented in the README. With positions expressed as screen fractions and no documented handling for that case, the first thing to check after a machine changes desks is whether the script still hits the control it was recorded against.
The command line takes the repeat count as an argument
Every recording is a plain file under scripts, so a run does not need the window. The executable takes the path directly:
> ./KeymouseGo scripts/0314_1452.txtThe same flag sets how many times that file runs, in short or long form:
> ./KeymouseGo scripts/0314_1452.txt -rt 3
> ./KeymouseGo scripts/0314_1452.txt --runtimes 3A repeat count of zero means an endless loop, and that is the arrangement to think about before putting this on a machine you cannot reach. The documented way out of an infinite run is the F9 hotkey. Inside the desktop window the count is a field on the form instead.
Recording fails on a locked desktop, and macOS needs two accessibility entries
The README names the failure directly: on some systems the recorder captures an incomplete set of mouse events, and the answer is to run the tool as administrator or root.
macOS adds a second layer. The app has to be in the accessibility whitelist, and when you launch the packaged executable the terminal running it needs an entry there too. If the app quits on start instead, the documented remedy is write access to the Qt material directory:
chmod -R 770 ~/.qt_materialFor Linux and macOS, anyone still stuck after running with elevated rights is sent to the pynput limitations page, where the input backend states its own constraints. For an evaluation the practical consequence is short: check that a three click recording replays correctly on the machine you intend to use before building anything around it.
The MacOS entry of the packaging guide carries no command
KeymouseGo ships as a packaged executable, so users without Python are pointed at the releases page and told to run the binary directly. Building from source is the other route, with its own steps: Python 3, the dependency set, pyinstaller, then a bundle command.
pip install -r requirements-windows.txt
pip3 install -r requirements-universal.txt
pip install pyinstallerThe bundle command changes with the display server, because the hidden imports name the pynput backend to use:
pyinstaller -F -w --add-data "./assets;assets" KeymouseGo.py
pyinstaller -F -w --add-data "./assets:assets" --hidden-import "pynput.keyboard._xorg" --hidden-import "pynput.mouse._xorg" KeymouseGo.pyThose two lines cover Windows and Linux on X11, with a third variant for Wayland using the uinput imports, and the executable lands in the dist folder of the project directory. The MacOS entry in that same list has no command at all. A macOS user building from source has to work the invocation out from lines written for X11 and Wayland, which are different backends, or fall back on the packaged release.
Recorder, events, plugins and Qt widgets sit in separate folders
KeymouseGo.py is the entry point, and the tree around it splits the work by stage: Recorder/ for capturing input, Event/ for the events themselves, Plugin/ for extensions, Util/ for helpers. The interface is Qt, and that shows in the file names rather than in a framework note. UIView.ui and UIFileDialogView.ui are the form definitions, UIFunc.py and UIFileDialogFunc.py hold their logic, assets.qrc and assets_rc.py carry the compiled resources, and Internationalizing.pro marks the translation project.
Two things follow for anyone extending it. Contributions are pulled into the dev branch, so work in progress is kept off master deliberately, and the script syntax reference lives in the project wiki while the readme stops at the basic event list. There is also a top level archived/ directory beside the live packages, so retired code stays in the tree instead of disappearing with its last commit.
GPL-2.0, and commits on master that postdate the newest release
The licence is GPL-2.0, which matters if you plan to ship something built on it: a distributed derivative carries the copyleft terms with it, so an in house script stays your own affair while a bundled binary is a different question. That is the licence text, not advice.
The release history is uneven. v5.1.1 shipped on 2023-02-10, v5.2 on 2025-03-12 and v5.2.1 on 2025-04-19, while the last push to the repository is dated 2026-06-07. The repository has been pushed to since then, but anyone installing from releases runs code from April 2025 and not the current master. A bug report worth reading has to say which of the two it came from, and a fix that landed after the tag means building from source with the packaging step above.
Editorial conclusion
KeymouseGo suits someone who wants a desktop recorder for short fixed click sequences on a single machine and is willing to edit the generated json5 file afterwards. It does not suit work that needs a recorded cursor path or a macOS build from source, since no build command is given for that platform. Before adopting it, record a three click sequence on the target machine, replay it, and open the file it wrote under scripts to see whether the delays and the percentage coordinates match the job.
Frequently asked questions
What Python library can I use to control the mouse and keyboard?
KeymouseGo is an application, not a library you import. It is written in Python, its dependencies come from requirements-windows.txt on Windows and requirements-universal.txt on Linux and macOS, and its input events go through pynput.
Is there a way to automate mouse clicks?
KeymouseGo records your clicks and keystrokes, stops the recording, and replays the sequence from the start button or the F6 hotkey. Movement of the pointer between clicks is not captured.
Does KeymouseGo record where the mouse moves?
No. The recorder keeps mouse clicks and keyboard input and leaves out the movement in between, so a job that relies on hovering, dragging or selecting a region has to be written by hand instead.
How do I stop a KeymouseGo script that loops forever?
Set the repeat count to 0 for an endless loop, then press F9. That hotkey is the default stop key and halts a script that is currently running.
Why does recording miss clicks on macOS?
The app has to be in the macOS accessibility whitelist, and the terminal has to be there too when the packaged executable is used. If the app quits on start, the README asks for write access to the Qt material directory with chmod -R 770 ~/.qt_material.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/taojy123-keymousego)Star history chart for your README
[](https://hysenlabs.com/projects/taojy123-keymousego)Was this useful?