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 set SOUND_* (or SYS_SOUND_*) in ~/.config/breaktimer.conf (see Configuration below) 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 config     # print the effective settings

(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). start is idempotent: run_loop claims the PID file atomically (noclobber), so a second start — or a fast double-login — can't spawn a duplicate daemon; the loser aborts and a stale PID file from a previous session is taken over, not duplicated.

Configuration

Defaults live at the top of breaktimer.sh. To change them without editing a tracked file, write ~/.config/breaktimer.conf (or $XDG_CONFIG_HOME/breaktimer.conf). It is sourced as shell, so it is a list of assignments, and it need only name what it changes:

MICRO_MIN=25
BREAK_MIN=5
WORK_START="08:30"
SOUND_MICRO="$HOME/Music/notify/pausetta.opus"

variable	default	meaning
`MICRO_MIN`	30	minutes of work between breaks
`BREAK_MIN`	3	length of a micro-pause
`LONG_MIN`	10	length of a long pause
`LONG_EVERY`	4	a long pause instead of every Nth micro-pause
`WORK_START`	09:00	countdown freezes before this
`WORK_STOP`	18:30	countdown freezes after this
`URGENCY_MICRO`	normal	notify-send urgency for a micro-pause
`URGENCY_LONG`	critical	notify-send urgency for a long pause
`SOUND_MICRO`	unset	sound for a micro-pause, falls back to `SYS_SOUND_MICRO`
`SOUND_LONG`	unset	sound for a long pause, falls back to `SYS_SOUND_LONG`
`SOUND_BACK`	unset	sound for going back to work, falls back to `SYS_SOUND_BACK`

Check what is in effect:

breaktimer.sh config

The file is read when the daemon starts, so a change takes effect on breaktimer.sh restart. A syntax error in it is reported on stderr, but the script can carry on with the defaults; run breaktimer.sh config to confirm the values actually in effect.

The check for all of this is ./test-breaktimer-config.sh.

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.