breaktimer

Break reminder for Linux/Wayland. A small Bash daemon that nudges you to take micro-pauses while working at the PC, with desktop notifications, sounds, and a Waybar module showing a live countdown.

Notifications and tooltips are in Italian.

How it works

State machine: working → micro-pause → working, and every 4th block a long pause instead. The countdown freezes when you pause manually and outside your work-hours window, so breaks never eat into work time and the Waybar number stays honest.

Phase	Default	Notification
working	30 min	—
breaking	3 min	"🚶 Micro-pausa"
longbreak	10 min	"⏸️ Pausa lunga" (every 4th)

Dependencies

dunst (or any notify-send provider)
pipewire — pw-play, falls back to paplay (PulseAudio)
coreutils, Bash
Waybar (optional, for the bar module)
A Nerd Font for the Waybar glyphs (optional)

Install

The Waybar config calls the scripts from ~/bin. Put both there and make them executable:

mkdir -p ~/bin
cp breaktimer.sh waybar-breaktimer.sh ~/bin/
chmod +x ~/bin/breaktimer.sh ~/bin/waybar-breaktimer.sh

Make sure ~/bin is on your PATH (or call the scripts by full path).

Sounds

Defaults use the Modern Minimal UI sound set at:

~/.local/share/sounds/modern-minimal-ui-sounds/stereo/

Three events map to message-new-instant.oga (micro), alarm-clock-elapsed.oga (long), service-login.oga (back to work). Don't have that set? Either install it there, or edit the SOUND_DIR / SYS_SOUND_* variables at the top of breaktimer.sh to point at any .oga/.wav you like (e.g. the freedesktop sounds in /usr/share/sounds/freedesktop/stereo/). A missing file is simply silent — no error.

Usage

breaktimer.sh start      # start the daemon in the background
breaktimer.sh stop       # stop it
breaktimer.sh restart    # stop + start
breaktimer.sh pause      # freeze the countdown
breaktimer.sh resume     # unfreeze
breaktimer.sh toggle     # pause/resume in one command
breaktimer.sh status     # print state, phase, seconds remaining

(breaktimer.sh run is the internal loop — don't call it directly; it will refuse if a daemon is already running.)

Auto-start on login by adding breaktimer.sh start to your compositor's autostart (e.g. Hyprland exec-once, Sway exec).

Configuration

Edit the variables at the top of breaktimer.sh:

Variable	Meaning
`MICRO_MIN` / `BREAK_MIN`	work block / micro-pause length (minutes)
`LONG_MIN` / `LONG_EVERY`	long-pause length / every N-th block
`WORK_START` / `WORK_STOP`	work-hours window (`HH:MM`); outside it the work countdown freezes
`URGENCY_MICRO` / `URGENCY_LONG`	dunst urgency (`low`/`normal`/`critical`)
`SOUND_DIR`, `SOUND_`, `SYS_SOUND_`	sound files (see above)

Waybar integration

Three pieces:

waybar-breaktimer.sh — emits JSON ({text, class, tooltip}) that Waybar renders. Reads the daemon's state files; no recalculation.
waybar-breaktimer.config.jsonc — the custom/breaktimer module.
breaktimer.css — phase colors (Catppuccin).

1. Add the module

Paste the inner block of waybar-breaktimer.config.jsonc into your ~/.config/waybar/config modules, then add "custom/breaktimer" to one of your modules-left/center/right arrays:

"custom/breaktimer": {
    "exec": "~/bin/waybar-breaktimer.sh",
    "return-type": "json",
    "interval": 5,
    "on-click": "~/bin/breaktimer.sh toggle",     // left-click: pause/resume
    "on-click-right": "~/bin/breaktimer.sh restart", // right-click: restart
    "tooltip": true
}

2. Add the styling

Append breaktimer.css to ~/.config/waybar/style.css. It colors the module by phase:

Class	Color	Meaning
`working`	green	working
`breaking`	blue	micro-pause
`longbreak`	purple	long pause
`paused`	yellow	manually paused
`stopped`	grey	daemon not running

3. Reload

breaktimer.sh start
killall -SIGUSR2 waybar   # reload Waybar

Left-click the module to pause/resume, right-click to restart.