pycaffeine

Keep computer awake by moving the cursor by 1 pixel back and forth every few seconds

Table of Contents

• Features
• Usage
• Desktop Environment Notes (Linux)
• Development and Testing
  • Setup
  • Running Unit Tests
  • Build
  • Other Tasks
• License
• Support

Features

• System tray application with start/stop controls
• Native sleep/screensaver inhibition (D-Bus on Linux, SetThreadExecutionState on Windows, caffeinate on macOS)
• Mouse simulation to also appear "Active" in chat apps (Teams/Slack)
• Configurable interval (5s, 15s, 30s, 45s, 60s) from the tray menu
• Cross-platform (Linux, Windows, macOS)
• Standalone executable via PyInstaller

Usage

# Run from source
uv run python -m pycaffeine

Or download the latest standalone executable from Releases.

The app runs in the system tray. Right-click the tray icon to start, stop, change the interval, or quit.

Desktop Environment Notes (Linux)

Environment	Tray icon	Sleep inhibit	Mouse simulation
KDE / XFCE / Cinnamon (X11 or Wayland)	✓	✓	✓ (Wayland needs XWayland 23.2+)
Ubuntu GNOME	✓	✓	✓
Vanilla GNOME (e.g. Fedora)	needs AppIndicator extension ¹	✓	✓

• ¹ GNOME tray icon: GNOME removed legacy tray support; install the AppIndicator extension / gnome-shell-extension-appindicator package (preinstalled on Ubuntu).
• Mouse simulation on Wayland: requires XWayland 23.2+ with libei support (Plasma 6, GNOME 45+). Sleep inhibition works regardless.

Development and Testing

Requires UV to be installed.

Setup

uv lock --upgrade && uv sync --all-extras --all-groups

Running Unit Tests

poe test

Build

Build a standalone executable with PyInstaller:

poe build

The executable will be generated in the ./dist directory.

Other Tasks

poe linter
poe updatedev

License

Released under the MIT License

Support

If you find this project helpful, consider supporting development.