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

1. 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/

2. 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
   }

3. 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;
        }
    }

4. 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:

   • Freesound.org
   • Pixabay.com/sounds
   • Zapsplat.com

   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

1. 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
DBL Left Click	Any other state	Reset to Disable timer (300ms)
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

1. Scroll down on the module (or run ./timer.sh pomo)
2. 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
3. Left click to start
4. 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.