# 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.