Mouse jiggler for Linux: X11, Wayland and what actually works

Keeping the screen on is not the same as looking active

The first thing most people find is the sleep tooling: xset s off and xset -dpms to stop the screen blanking, systemd-inhibit to hold off suspend, the Caffeine applet, or simply switching Automatic Suspend off in the GNOME power settings. All of them do their job well, and none of them produce a single event of input.

A tracker does not score the state of your display. It scores the input inside each interval — pointer movement, keystrokes, clicks — and a machine with a bright screen and an untouched keyboard hands in an empty block just like a sleeping one. Solving suspend solves suspend; the idle question sits one layer down.

How a Linux desktop decides you are idle

On X11 there is a single well-defined answer. The MIT-SCREEN-SAVER extension exposes an idle counter — milliseconds since the last keyboard or pointer event — and that is exactly what xprintidle reads, what the screen locker reads, and what a monitoring agent reads. One number, available to any process that can open the display.

On Wayland there is no such shared number. The compositor owns input, and it decides what to tell applications: GNOME exposes an idle monitor over D-Bus, wlroots-based compositors implement the ext-idle-notify protocol, and some setups expose nothing at all. This is a deliberate security design rather than an oversight, and it is the single biggest practical difference between the two worlds.

• X11 — MIT-SCREEN-SAVER gives a global idle counter to any client.
• Wayland — no global counter; the compositor decides what to expose.
• GNOME on Wayland — an idle monitor is available over D-Bus.
• wlroots compositors — the ext-idle-notify protocol, when built in.

The DIY route: xdotool, ydotool and a while loop

The scripts you find on GitHub are almost all the same three lines: a loop that calls xdotool mousemove_relative -- 1 0, sleeps, and moves back. On X11 this works, because xdotool talks to the XTEST extension, which injects synthetic input the same way a real device would — the idle counter resets, and the tracker sees movement.

Under Wayland the same command fails, because there is no X display to inject into. The usual replacement is ydotool, which writes to /dev/uinput and therefore creates a virtual input device at the kernel level. That works across compositors, but it wants access to uinput — a root daemon or a udev rule — and handing a background script that privilege is a real decision, not a footnote.

• xdotool — X11 only, no extra privileges, injects through XTEST.
• ydotool — works under Wayland, needs access to /dev/uinput.
• Python with pyautogui — same X11 limitation underneath.
• XWayland is not a way out: it carries XTEST but not the idle counter.

The XWayland trap worth knowing about

Running an X11 tool inside a Wayland session through XWayland looks like it should bridge the gap, and it half does. XTEST is there, so the pointer genuinely moves. MIT-SCREEN-SAVER is not, so anything that tried to read idle time the X11 way gets an error rather than a number.

The practical consequence is a jiggler that moves the cursor but has no idea whether you are at the desk — so it keeps nudging while you are working, which is precisely the behaviour that makes a tool feel broken and makes its output look mechanical. Anything serious on Wayland has to get its idle signal from the compositor, or infer it another way and say so plainly.

Why a one-pixel loop gets noticed

A three-line script produces motion, but always the same motion: a dead-straight jump of a fixed size at a fixed cadence, forever. A tracker that only asks "was there input" counts it. A tracker that looks at the shape of the input has an easy job — human pointer movement has curves, acceleration, overshoot and pauses, and a metronome has none of them.

The same goes for the resulting numbers. Real work produces an activity percentage that wanders; a loop produces a flat line, and a flat line at a suspiciously round value is more conspicuous than a lower, moving one. The detection mechanics are covered in the related reading.

Distribution barely matters, the display server decides everything

The searches split by distribution — Ubuntu, Mint, Arch — but the distribution is almost never the variable that matters. Every mainstream desktop ships both stacks, and what determines whether a given tool works is which session you logged into, not which package manager you use.

Checking takes one command: echo $XDG_SESSION_TYPE prints x11 or wayland. Ubuntu and Fedora default to Wayland on GNOME; KDE offers both; older or NVIDIA-heavy setups often still land on X11. Answer that question first and most of the contradictory advice online sorts itself out.

• echo $XDG_SESSION_TYPE — the only check that matters.
• x11 — xdotool, xprintidle and the classic scripts all work.
• wayland — uinput-level input, compositor-level idle, or nothing.

What a presence app adds over the script

The gap between a loop and a tool people keep using is not the moving part, it is everything around it: motion along curves with micro-pauses instead of a fixed jump, an uneven key rhythm, scrolling and window switching so the screen actually changes, and a hard rule that none of it happens while you are at the keyboard.

That last one is what makes it usable rather than annoying. A script that nudges the cursor while you are typing fights you; a presence tool that reads idle time properly is invisible until you leave and stops the moment you come back.

Where the honest limits are

No amount of input simulation changes what a screenshot shows, and it does not write code or answer messages. Anything that claims to be undetectable is selling certainty nobody can hold, because detection is a moving target on the tracker side. What input simulation does is keep an idle machine from reading as an empty block — that is the whole job, and it is worth being precise about it.

Where Reaction fits

Reaction ships a native Linux build alongside Windows. It moves the pointer along smooth curves, varies the key rhythm, scrolls and switches windows on a schedule that is not a timer, and runs only while the machine is genuinely idle — the moment you touch the mouse it stops and hands control back.

It reads idle time through the X11 screen-saver counter where that exists. Under Wayland that counter is unavailable by design, so the honest statement is that X11 sessions get the full behaviour and Wayland coverage depends on the compositor — a limitation shared by every tool in this category, whether or not it says so.