1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
# 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](https://github.com/Alexays/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](https://github.com/Alexays/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:
```bash
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](https://github.com/cadecomposer/modern-minimal-ui-sounds) 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
```bash
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:
```jsonc
"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
```bash
breaktimer.sh start
killall -SIGUSR2 waybar # reload Waybar
```
Left-click the module to pause/resume, right-click to restart.
## License
GPLv2 β see [LICENSE](LICENSE). Copyright (C) 2026 Danilo M.
|
