timesup

Blazingly fast simple cli timer with Linux notifications using notify-send

Features

• Simple durations like 1h30m, 45m, 30s, or 1h20m5s
• Repeat mode: Run timers continuously with --repeat
• Get notified via notify-send when timer completes
• Audio alarm: Plays a chime sound when timer completes (default, but can be muted with --mute)
• Custom sounds: Use your own audio files (WAV, MP3, FLAC, OGG) with --sound
• Set your own notification message with --msg
• Interactive notifications: Click Kill Timer button in notification to stop repeating timers or call timesup kill
• Runs in background as a daemon
• Single instance: Only runs one timer runs at a time

Installation Options

From crates.io

cargo install timesup

From source

git clone https://github.com/neonvoidx/timesup.git
cd timesup
cargo install --path .

Build locally

cargo build --release
sudo cp target/release/timesup /usr/local/bin/

Usage

Basic timer

# 5 second timer
timesup 5s
# More complex duration example 
timesup 2h30m15s

Custom notification message

timesup 25m --msg "Time to take a break!"

Mute default alarm sound

# Silent timer (notification only, no sound)
timesup 30m --mute

Custom sound file

# Use your own alarm sound (supports WAV, MP3, FLAC, OGG)
timesup 5m --sound ~/sounds/alarm.wav

Repeating timer

# Pomodoro timer - 60 minute work sessions
timesup 60m --repeat --msg "Break time!"

Killing timers

# Kill from command line, this will kill any running timer
# Or you can click the "Kill Timer" button inside the notification popup
timesup kill

Check timer status

# See current timer information
./target/release/timesup status
# Output
⏱️  Timer Status:
   Duration: 5s (5s)
   Elapsed: 2s (2s)
   Remaining: 3s (3s)
   Repeat: yes
   Message: Timer finished!

Requirements

• Linux with a notification daemon (e.g., dunst, mako, notification-daemon)
• notify-send command (usually from libnotify package)

Other info

• pid (while running) file is stored at /tmp/timesup.pid
• Error file at /tmp/timesup.err

Attribution

Default chime sound: Chime_01.wav by Andromadax24 -- https://freesound.org/s/186719/ -- License: Attribution 4.0