smart-scroll

A system-wide "hold and aim" auto-scroll daemon for Linux. Press a toggle key, then move the mouse up or down — the further from where you toggled it on, the faster it scrolls. Works in any window, under both X11 and Wayland, because it reads raw input via evdev and injects scroll events via a virtual uinput device rather than talking to the display server.

How it behaves

• Toggle (default: middle-click / wheel click): click once to arm, click again to disarm — hands-free, no holding required.
• While armed, moving the mouse up/down sets direction and speed. There's a small dead zone near the arming point so tiny jitter doesn't scroll.
• Stop moving and the speed relaxes back toward zero on its own.
• Esc always disarms, as a safety net.
• Nothing is grabbed exclusively — normal mouse/keyboard behavior is untouched the rest of the time. One consequence: on X11, middle-click also pastes the primary selection in most apps, so a click will both toggle scroll and paste whatever's selected. If that's a problem, set toggle_key = "BTN_SIDE" (or BTN_EXTRA) in your config instead — see config.py for details.

Install

1. Dependencies

   pip install evdev --break-system-packages
   

2. Permissions — this needs to read /dev/input/event* and write to /dev/uinput.

   sudo usermod -aG input $USER
   sudo cp 99-smart-scroll-uinput.rules /etc/udev/rules.d/
   echo uinput | sudo tee /etc/modules-load.d/uinput.conf
   sudo modprobe uinput
   sudo udevadm control --reload-rules && sudo udevadm trigger
   

   Log out and back in (group membership only takes effect on a fresh login).

3. Try it directly first, before wiring up the service:

   python3 smart_scroll.py
   

   Middle-click, nudge the mouse up or down, and confirm it scrolls. If it scrolls the wrong way, set invert_direction = true in your config (see below) — wheel-direction convention varies a bit by hardware/driver.

4. Run at boot (optional) via the included system service:

   sudo mkdir -p /opt/smart-scroll
   sudo cp smart_scroll.py config.py /opt/smart-scroll/
   sudo sed "s/CHANGE_ME/$USER/" smart-scroll.service | sudo tee /etc/systemd/system/smart-scroll.service
   sudo systemctl daemon-reload
   sudo systemctl enable --now smart-scroll.service
   

   Check it with systemctl status smart-scroll and journalctl -u smart-scroll -f.

Configuring

Create ~/.config/smart-scroll/config.toml to override any default — see the top of config.py for every available field and its meaning (toggle/panic keys, dead zone, max speed, decay rate, etc.).

Known rough edges

• Direction sign (does moving the mouse down scroll the page down or up) isn't guaranteed the same across all mice/compositors — flip invert_direction if it feels backwards.
• The service runs system-wide (not per-desktop-session) since input devices aren't tied to a particular graphical session — this means it keeps working across TTY switches, X11, and Wayland alike.