Waybar Pomodoro Timer

A highly efficient, timer and pomodoro module for Waybar with mouse controls and CLI commands.

Preview

timerv2.mp4

What's New

Check out the latest updates and improvements! See Release Notes for detailed changelog.

Features

Dual Mode: Standard Timer and Pomodoro with customizable work/break cycles
Mouse and CLI controls (toggle, pause, resume, reset, skip)
Desktop notifications and sound effects
Dynamic visual feedback with state-specific icons and colors
Customizable presets and helpful tooltips
Persistent state across Waybar restarts, syncs across multiple waybar instances
minimal system resource footprint

Requirements

Waybar (obviously)
Notification daemon (for desktop notifications e.g. dunst, libnotify, mako, etc.)
Nerd Font installed for icons (e.g., JetBrains Mono, Cascadia Code, etc.)
PulseAudio or PipeWire (for sound playback via paplay)

Installation

Quick Installation

mkdir -p ~/.config/waybar/scripts ~/.config/waybar/sounds && \
curl -L https://raw.githubusercontent.com/niraletter/waybar-timer/main/timer.sh -o ~/.config/waybar/scripts/timer.sh && \
curl -L https://raw.githubusercontent.com/niraletter/waybar-timer/main/sounds/timer.mp3 -o ~/.config/waybar/sounds/timer.mp3 && \
chmod +x ~/.config/waybar/scripts/timer.sh

Or manually:

mkdir -p ~/.config/waybar/scripts ~/.config/waybar/sounds
# Save the script code to timer.sh
chmod +x ~/.config/waybar/scripts/timer.sh
# Add your timer.mp3 sound or your audio files to ~/.config/waybar/sounds/

Add or update to waybar config (~/.config/waybar/config.jsonc)

Note: Do not add "interval" or "signal", as the script handles its own refresh loop.

// place the module
"modules-left": [
     "custom/timer"
 ],

// define the module
"custom/timer": {
    "exec": "~/.config/waybar/scripts/timer.sh",
    "return-type": "json",
    "format": "{}",
    "on-click": "~/.config/waybar/scripts/timer.sh click",
    "on-click-right": "~/.config/waybar/scripts/timer.sh right",
    "on-click-middle": "~/.config/waybar/scripts/timer.sh middle",
    "on-scroll-up": "~/.config/waybar/scripts/timer.sh down",
    "on-scroll-down": "~/.config/waybar/scripts/timer.sh up",
    "tooltip": true,
    "escape": true
}

Add to waybar style (~/.config/waybar/style.css)

Add these styles and customize colors, fonts, and animations to your preference.

Click to Expand CSS styling

 /* Waybar Timer */
 #custom-timer {
     background-color: #1e1e2e;
     /*color: #cdd6f4;*/
     padding: 0 9px;
     font-size: 15px;
     border-radius: 15px;
     font-family: "Doto";  /* place your font here */
      /* Link for the above font https://fonts.google.com/specimen/Doto  */
     font-weight: 900;
     transition: all 0.2s ease;
 }

 /* --- STATE: DISABLED (00:00, Idle) --- */
 #custom-timer.disabled {
     background-color: transparent;
     color: #bfbfbf;
     opacity: 0.6;
     font-weight: normal;
     animation-duration: 1s;
     animation-timing-function: ease-in-out;
     animation-direction: alternate;
 }

 /* --- STATE: IDLE (Active but 00:00) --- */
 #custom-timer.idle {
     background-color: transparent;
     color: #bfbfbf;
 }

 /* --- STATE: SELECTION MODE --- */
 #custom-timer.select {
     background-color: #373948;
     color: #85b2fa;
 }

 /* --- STATE: RUNNING (Normal Timer & Pomodoro Work) --- */
 #custom-timer.running {
     background-color: transparent;
     color: #cccccc;
 }

 /* --- STATE: POMODORO BREAK (New) --- */
 #custom-timer.pomo_break {
     background-color: transparent;
     color: #f9e2af; /* Yellow/Gold to distinguish break from work */
 }

 /* --- STATE: POMODORO MESSAGE (New: "Work 1/4") --- */
 #custom-timer.pomo_msg {
     background-color: transparent;
     color: #cba6f7; /* Lavender/Purple for status messages */
 }

 /* --- STATE: PAUSED --- */
 #custom-timer.paused {
     background-color: #404040;
     color: #f9e2af;
     /*border: 1px solid #f9e2af; */
 }

 /* --- STATE: WARNING (< 10s or 30s alert) --- */
 #custom-timer.warning {
     background-color: transparent;
     animation-name: red-alert;
     animation-duration: 1s;
     animation-timing-function: ease-in-out;
     animation-iteration-count: infinite;
     animation-direction: alternate;
 }

 /* --- STATE: DONE --- */
 #custom-timer.done {
     background-color: #bfbfbf;
     color: #11111b;
 }

 /* --- STATE: RESET ANIMATION --- */
 #custom-timer.reset {
     color: #ff4d4d;
     background-color: transparent;
 }

 /* -----------------------------------------------------------------------------
 * KEYFRAMES: Red Color Fading
 * ----------------------------------------------------------------------------- */
 @keyframes red-alert {
     0% {
         color: #ff4d4d; /* Bright, visible Red */
         opacity: 1;
     }
     100% {
         color: #ff4d4d;
         opacity: 0.8; /* Fade cleanly to 80% transparency */
         text-shadow: none;
     }
 }

Setup sound effects (optional)

Create the sounds directory if it's not already:
```
mkdir -p ~/.config/waybar/sounds
```
Default setup (single sound file):

Add one sound file to this directory:
- timer.mp3 - plays for all timer events (completion, transitions, etc.)
This repo includes a single timer.mp3 sound file by default. You can download your own from:
Advanced setup (multiple sound files):

You can customize the script to use different sounds for different events by editing the sound variables in timer.sh:
```
 SOUND_TIMER_DONE="${HOME}/.config/waybar/sounds/timer.mp3"
 SOUND_WORK_START="${HOME}/.config/waybar/sounds/timer.mp3"
 SOUND_BREAK_START="${HOME}/.config/waybar/sounds/timer.mp3"
 SOUND_BREAK_END="${HOME}/.config/waybar/sounds/timer.mp3"
 SOUND_COMPLETE="${HOME}/.config/waybar/sounds/timer.mp3"
```
The script uses paplay (compatible with both PulseAudio and PipeWire) to play sounds.

Note

The above quick installation script automatically creates and puts the audio file in your .config/waybar/sounds

Restart your waybar

Run:
```
pkill -USR2 waybar
```

Alias (Optional)

For easier access, add this alias to your ~/.bashrc or ~/.zshrc:

alias timer='~/.config/waybar/scripts/timer.sh'
# or
alias pomo='~/.config/waybar/scripts/timer.sh pomo'

Then source your shell config:

source ~/.bashrc  # or source ~/.zshrc

Now use: timer 20m5s, timer 1h30s, pomo 25m5m4s, pomo 40 10 2 etc.

Usage

Mouse Controls

Input	State	Behavior
Left Click	Disabled	Activate (Wake up module)
	Idle	Enter Standard Selection mode
	Select	Start timer
	Running	Pause timer
	Paused	Resume timer
Right Click	Idle	Disable module (Hide/Sleep)
	Select (Standard)	Cycle Presets (1m ➡ 5m ➡ 10m...)
	Select (Pomodoro)	Cycle Edit Mode (Work Time ➡ Break Time ➡ Session Count)
	Running (Pomodoro)	Skip Session (Instant Work ➡ Break or Break ➡ Work)
	Running (Standard)	Pause/Resume (same as Left Click)
Middle Click	Any	Reset (Cancel timer and return to Idle)
Scroll Up	Idle	Enter Standard Selection mode
	Any other state	Increase Time (+1 minute)
Scroll Down	Idle	Enter Pomodoro Selection mode
	Any other state	Decrease Time (-1 minute)

Note

Set POMO_ENABLED=false in timer.sh to disable pomodoro mode. When disabled, scroll down behaves like standard timer selection and pomo CLI is ignored; any active pomodoro session resets to idle.

CLI commands

Time setting (auto-start):

./timer.sh 10s        # 10 seconds
./timer.sh 5m         # 5 minutes
./timer.sh 1h         # 1 hour
./timer.sh 1h30m      # 1 hour 30 minutes
./timer.sh 1h20m2s    # 1 hour, 20 minutes, 2 seconds
./timer.sh 300        # 300 seconds

# New Arguments
./timer.sh toggle     # Toggle play/pause
./timer.sh pause      # Force pause timer
./timer.sh resume     # Force resume timer
./timer.sh reset      # Reset timer to idle
./timer.sh skip       # Skip current pomodoro session

Pomodoro:

Syntax: pomo [WORK] [BREAK] [SESSIONS]

./timer.sh pomo            # Default: 25m Work, 5m Break, 4 Sessions
./timer.sh pomo 50 10 2    # 50m Work, 10m Break, 2 Sessions
./timer.sh pomo 25m 5b 4s  # Explicit syntax

Mouse simulation:

./timer.sh click      # Left click (start/pause)
./timer.sh right      # Right click (presets/disable/skip)
./timer.sh middle     # Middle click (reset)
./timer.sh up         # Add (+1 minute)
./timer.sh down       # Sub (-1 minute)

Keyboard Shortcut example Setup Examples

Hyprland (~/.config/hypr/hyprland.conf):

bind = SUPER, P, exec, ~/.config/waybar/scripts/timer.sh 1h30m
bind = SUPER_SHIFT, P, exec, ~/.config/waybar/scripts/timer.sh pomo 25m 5b 4s 
bind = SUPER_CTRL, P, exec, ~/.config/waybar/scripts/timer.sh reset

i3/Sway (~/.config/i3/config or ~/.config/sway/config):

bindsym $mod+p exec ~/.config/waybar/scripts/timer.sh 5m
bindsym $mod+Shift+p exec ~/.config/waybar/scripts/timer.sh toggle
bindsym $mod+Ctrl+p exec ~/.config/waybar/scripts/timer.sh reset

How Pomodoro Mode works

Scroll down on the module (or run ./timer.sh pomo)
The module enters pomodoro select mode
- Text: [25]m | 5b | 4s (brackets indicate what scroll changes)
- Right click to cycle focus between minutes, break, and sessions
Left click to start
Flow:
- Work session 1 starts
- Sound effect + notification when done
- Break session 1 starts (auto-starts by default)
- Right-click to skip current work or break session
- Repeats until all sessions are done

Timer Presets

Right-clicking in SELECT mode (shows a plus sign in timer icon) cycles through these presets: 1m, 5m, 10m, 15m, 20m, 25m, 30m, 45m, 50m, 1h, 1h15m, 1h30m, 1h45m, 2h, 2h30m, 3h.

Configuration

Edit the top of timer.sh to customize timer presets, scroll seconds, auto break/work, inactivity time, and sound effects:

# --- STANDARD TIMER PRESETS (Seconds) ---
PRESETS=(60 300 600 900 1200 1500 1800 2700 3000 3600 4500 5400 6300 7200 9000 10800)
SCROLL_STEP=60
INACTIVITY_LIMIT=30

# --- POMODORO PRESET ---
POMO_PRESETS=(
    "25 5 4"
)

# Pomodoro Settings
POMO_ENABLED=true
POMO_AUTO_BREAK=true
POMO_AUTO_WORK=true

# --- SOUND EFFECTS ---
SOUND_TIMER_DONE="${HOME}/.config/waybar/sounds/timer.mp3"
SOUND_WORK_START="${HOME}/.config/waybar/sounds/timer.mp3"
SOUND_BREAK_START="${HOME}/.config/waybar/sounds/timer.mp3"
SOUND_BREAK_END="${HOME}/.config/waybar/sounds/timer.mp3"
SOUND_COMPLETE="${HOME}/.config/waybar/sounds/timer.mp3"

# Icons (Nerd Font symbols)
# ......
#.......

Notifications & Sounds

When a timer or pomodoro session completes, the script sends a notification via notify-send and plays a sound effect via paplay.

All notifications use normal urgency level to prevent them from becoming sticky or persistent in certain notification daemons.

Default behavior (single sound file):

All events play the same sound:

Standard timer finishes: timer.mp3
Work session finishes: timer.mp3
Break finishes, back to work: timer.mp3
All sessions complete: timer.mp3

Advanced customization (multiple sound files):

Edit the sound variables in timer.sh to use different sounds for different events:

Standard timer finishes: timer_done.mp3
Work session finishes: break_start.mp3
Break finishes, back to work: work_start.mp3
All sessions complete: complete.mp3

Behavior Details

Inactivity handling

Timer automatically disables after 30 seconds of inactivity
Timer stays active when running/paused

Warning states

30-27 seconds remaining: warning icon and styling
≤10 seconds remaining: warning icon and styling with blink animation

Uninstall

To remove the script run:

rm -f ~/.config/waybar/scripts/timer.sh
rm -rf ~/.config/waybar/sounds  # optional: remove sound files

Contributing

Contributions are welcome ❤️
If you have ideas for improvements or find bugs, feel free to open an issue or submit a pull request.

License

This project is licensed under the MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 54 Commits
assets		assets
sounds		sounds
LICENSE		LICENSE
README.md		README.md
timer.sh		timer.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Waybar Pomodoro Timer

Preview

What's New

Features

Requirements

Installation

Alias (Optional)

Usage

Mouse Controls

CLI commands

Keyboard Shortcut example Setup Examples

How Pomodoro Mode works

Timer Presets

Configuration

Notifications & Sounds

Behavior Details

Inactivity handling

Warning states

Uninstall

Contributing

License

About

Uh oh!

Releases 6

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Waybar Pomodoro Timer

Preview

What's New

Features

Requirements

Installation

Alias (Optional)

Usage

Mouse Controls

CLI commands

Keyboard Shortcut example Setup Examples

How Pomodoro Mode works

Timer Presets

Configuration

Notifications & Sounds

Behavior Details

Inactivity handling

Warning states

Uninstall

Contributing

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 6

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages