Hourglass

A Linux screen time limiter daemon written in Rust. Hourglass enforces daily screen time limits for users on graphical sessions (X11/Wayland), with configurable warnings and automatic session termination when time runs out.

This project was largely generated by Claude Opus 4.6, with manual review and adjustments by zvchei.

Features

• Per-user daily limits — configure independent time allowances for each user
• Daemon-based enforcement — a systemd service polls active graphical sessions every 10 seconds
• Warnings before logout — desktop notifications (via zenity or notify-send) at 15 min, 5 min, and 1 min remaining
• Automatic session termination — calls loginctl terminate-user when time expires
• Time extensions — grant extra minutes on the fly without changing the base limit
• Atomic state persistence — usage data stored in /var/lib/hourglass/state.json, written atomically with file locking

Requirements

• Linux with systemd and loginctl
• A graphical session (X11 or Wayland)
• zenity and/or notify-send for desktop notifications
• Rust toolchain (to build from source)

Building

cargo build --release

The release binary is placed at target/release/hourglass.

Packaging

./package.sh

This cleans previous build artifacts, builds a release binary, runs tests, and produces hourglass.tar.gz containing the binary, install/uninstall scripts, and service config.

Installation

sudo ./install.sh

This will:

1. Copy the binary to /usr/local/bin/hourglass
2. Install and enable the hourglass.service systemd unit
3. Add a PAM hook to /etc/pam.d/common-account to block login when time is exhausted

Uninstallation

sudo ./uninstall.sh

Removes the binary, systemd service, and PAM hook. Config and state files in /etc/hourglass and /var/lib/hourglass are preserved.

Usage

All commands require root except status.

# Set a 120-minute daily limit for a user
sudo hourglass set-limit alice 120

# Grant 30 extra minutes for today
sudo hourglass extend alice 30

# Show status for a specific user
sudo hourglass status alice

# Show status for all managed users
sudo hourglass status

# Remove a user's limit
sudo hourglass remove-limit alice

# Run the daemon (normally handled by systemd)
sudo hourglass daemon

Configuration

Config is stored at /etc/hourglass/config.toml:

[users.alice]
daily_limit_minutes = 120

[users.bob]
daily_limit_minutes = 60

How it works

1. The daemon polls loginctl every 10 seconds for active graphical sessions
2. For each managed user with an active session, it increments their used_seconds
3. When remaining time hits a warning threshold, a desktop notification is sent
4. When time runs out, the user is notified and their session is terminated via loginctl terminate-user
5. State resets daily — a new day starts fresh usage tracking
6. At login time, PAM checks whether the user's limit is already exhausted and denies the session if so

Known issues

• glibc version binding — The binary is dynamically linked against glibc. Building on a system with a newer glibc produces a binary that won't run on systems with an older glibc. To target older distributions, build inside a container or VM matching the oldest target distro. Binaries built against an older glibc will run on newer systems (glibc is backwards-compatible).

License

This project is published under the MIT License.