TimeHUD

A lightweight, transparent HUD overlay for Linux — shows a system clock and stopwatch / countdown timer above fullscreen apps (YouTube, Netflix, etc.).

---

Quick start

Pre-built binaries

curl -sSL https://raw.githubusercontent.com/13/timehud/main/install-appimage.sh | sh

# 1. Install dependencies (creates .venv automatically)
bash install.sh
# 2. Run
./timehud
# Or with a position override:
./timehud --position bottom-right

---

Manual install (no venv)

pip install .# or: pip install .[hotkeys] for global hotkeys
timehud

(The old PYTHONPATH=src invocation still works; keep it as a one-line alternative for running from a checkout without installing: PYTHONPATH=src python -m timehud.main.)

---

Controls

Overlay buttons

Button	Action
▶ / ⏸	Start / pause timer
↺	Reset timer to zero
SW/CD/IV	Toggle Stopwatch ↔ Countdown ↔ Interval mode

Timer Label Mouse Interactions

You can also interact directly by clicking on the countdown/stopwatch numbers:

Action	Result
Single Click	Start / pause timer
Double Click	Reset timer to zero
Scroll Wheel	Toggle Stopwatch ↔ Countdown ↔ Interval mode

Right-click context menu

• Settings – full settings dialog
• Presets – one-click countdown, interval (work/rest for a total time, e.g. 45/15 for 10 min) and stopwatch (work/rest cycles counting upward forever) presets; save the current countdown as a preset or manage them in Settings
• Theme – switch between built-in looks
• Click-Through – toggle mouse pass-through
• Opacity – quick opacity change
• Position – snap to screen corner
• Quit

Keyboard shortcuts (overlay window focused)

Key	Action
Space	Start / pause timer
R	Reset timer
Escape	Hide overlay
Ctrl+Q	Quit

Global hotkeys (requires pynput)

Shortcut	Action
Ctrl+Shift+Space	Start / pause timer
Ctrl+Shift+R	Reset timer
Ctrl+Shift+H	Show / hide overlay

---

Settings

Right-click → Settings or edit ~/.config/timehud/config.json:

{
"theme": "classic",
"position": "top-right",
"opacity": 0.88,
"font_size": 30,
"font_family": "Monospace",
"timer_mode": "stopwatch",
"countdown_duration": 300,
"interval_work": 40,
"interval_rest": 20,
"interval_rounds": 8,
"progress_style": "line",
"row_spacing": 6,
"show_clock": true,
"show_timer": true,
"sound_enabled": true,
"sound_interval": 60,
"sound_file": "",
"click_through": false,
"alert_last_5_seconds": false,
"auto_restart_countdown": false,
"presets": [
{ "name": "1 min", "duration": 60 },
{ "name": "5 min", "duration": 300 }
],
"active_preset": ""
}

Position presets

top-left · top-right · bottom-left · bottom-right · top-center · bottom-center

You can also drag the overlay anywhere — the position is saved automatically.

Themes

Right-click → Theme (or Settings → Display): Classic (default), Terminal, Glass, Mono. Picking a theme sets the color defaults — you can still customize individual colors afterwards in Settings.

Sound alerts

Set sound_interval (seconds) and sound_enabled: true.
Leave sound_file empty to use the built-in 880 Hz beep, or point it to any .wav/.mp3/.ogg file.

Requires one of these audio players: paplay (PulseAudio/PipeWire), aplay, ffplay, or mpv.

If alert_last_5_seconds is enabled, the timer will play short beeps at 5, 4, 3, 2, and 1 seconds remaining. On 0, it plays a long beep. Additionally, the timer text will flash its warning color on these exact seconds.

Interval mode

Work/rest rounds for training (default 40 s work / 20 s rest × 8 rounds, configurable in Settings → Timer). The round counter shows WORK 3/8 / REST 3/8, rest phases tint the timer blue, and a thin progress bar under the timer depletes through each phase. A long beep marks every phase end (toggleable per preset), and an optional fast double beep fires at half of each work phase; the session ends after the last work phase.

---

Wayland note

By default the app runs under XWayland for reliable always-on-top behaviour above fullscreen apps.
Pass --wayland to use the native Wayland backend (overlay may not appear above fullscreen in that mode).

---

Packaging

Arch Linux (AUR-style)

cd packaging/aur && makepkg -si

See packaging/aur/README.md for publishing to the AUR.

AppImage - manual build

./build.sh

Run the built image:

chmod +x ./*.AppImage
./*.AppImage

AppImage - GitHub Actions

The workflow file is .github/workflows/build-appimage.yml and supports:

• tag push (v*) -> builds AppImage, uploads artifact, and creates a GitHub Release asset
• manual run (workflow_dispatch) -> builds AppImage and uploads artifact

Trigger a release build from your machine:

git tag v0.1.0
git push origin v0.1.0

Trigger a manual build in GitHub:

1. Open Actions -> Build AppImage
2. Click Run workflow
3. Download TimeHUD-AppImage from the run artifacts