# 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

```bash
cargo install timesup
```

### From source

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

### Build locally

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

## Usage

### Basic timer

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

### Custom notification message

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

### Mute default alarm sound

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

### Custom sound file

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

### Repeating timer

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

### Killing timers

```bash
# 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

```bash
# 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
