TaskBeep - Pomodoro Timer

A Pomodoro timer with productivity tracking that plays a beep sound at the end of each interval.

Features

• Start timer with a custom topic and interval
• Receive beep notification when timer completes
• Signal whether you were working or wasting time
• Track productivity statistics by topic
• Integration-friendly (designed for use with Waybar or other status bars)

Usage

Start a Pomodoro Session

# Default 25-minute (1500s) session
taskbeep start "Writing documentation"

# Custom interval (e.g., 45 minutes)
taskbeep start "Deep work coding" 2700

The timer will:

1. Run in the background for the specified interval
2. Play a beep sound when the interval completes
3. Wait for your response about how productive you were

Respond to Timer

When the timer beeps, signal whether you were productive:

# Signal that you were working on the task
taskbeep working

# Signal that you were wasting time
taskbeep wasting

Check Status

# Human-readable format (default)
taskbeep status

# JSON format (for scripting)
taskbeep status --format json

# Plain key=value format (for parsing)
taskbeep status --format plain

Shows:

• Current status (running/paused/waiting)
• Current topic
• Interval length
• Sessions completed
• Time remaining
• Whether waiting for working/wasting response

The --format flag supports three output formats:

• human (default): Human-readable multi-line output
• json: Structured JSON for easy parsing in scripts
• plain: Simple key=value pairs, one per line

View Statistics

taskbeep stats

Shows:

• Total sessions (working vs wasting)
• Overall productivity percentage
• Breakdown by topic with individual productivity rates

Stop Timer

taskbeep stop

Integration with Waybar

You can integrate this with Waybar to create a visual Pomodoro timer. Here's an example configuration:

Waybar Config (~/.config/waybar/config)

{
    "custom/pomodoro": {
        "exec": "~/.config/waybar/scripts/pomodoro.sh",
        "return-type": "json",
        "interval": 1,
        "format": "󰔛 {text}",
        "escape": false,
        "tooltip": false,
        "on-click": "~/.config/waybar/scripts/pomodoro.sh working",
        "on-click-middle": "~/.config/waybar/scripts/pomodoro.sh toggle",
        "on-click-right": "~/.config/waybar/scripts/pomodoro.sh wasting",
    }
}

Pomodoro script (~/.config/waybar/scripts/pomodoro.sh)

#!/usr/bin/env bash
export PATH="$HOME/.cargo/bin:$PATH"

cmd="$1"

if [[ -n "$cmd" ]]; then
    case "$cmd" in
    working)
        taskbeep working
        exit 0
        ;;
    toggle)
        taskbeep toggle
        exit 0
        ;;
    wasting)
        taskbeep wasting
        exit 0
        ;;
    *)
        echo "Unknown command"
        exit 1
        ;;
    esac
fi

raw=$(taskbeep status --format plain 2>/dev/null)

if [[ $? -ne 0 ]] || [[ -z "$raw" ]]; then
    echo '{"text":"Idle", "class":"idle"}'
    exit 0
fi

status=""
remaining_seconds=0

while IFS='=' read -r key value; do
    case "$key" in
    status)
        status="$value"
        ;;
    remaining_seconds)
        remaining_seconds="$value"
        ;;
    esac
done <<<"$raw"

case "$status" in
running)
    minutes=$((remaining_seconds / 60))
    seconds=$((remaining_seconds % 60))
    text=$(printf "%02d:%02d" "$minutes" "$seconds")
    class="running"
    ;;
paused)
    text="Paused "
    class="paused"
    ;;
waiting)
    text="Waiting"
    class="waiting"
    ;;
*)
    text="Idle"
    class="idle"
    ;;
esac

echo "{\"text\":\"$text\", \"class\":\"$class\"}"

Waybar Style (~/.config/waybar/style.css)

#custom-pomodoro {
    padding: 0 10px;
    background-color: #22223b;
}
#custom-pomodoro.running { color: #38b000; }
#custom-pomodoro.paused  { color: #ffd60a; }
#custom-pomodoro.waiting { color: #ff1744; }

This configuration:

• Shows remaining time in the status bar
• Left-click to signal "working"
• Middle-click to pause/resume the timer
• Right-click to signal "wasting"

Workflow Example

1. Start your work session:

   taskbeep start "Implement new feature" 1500
   

2. Work on your task for 25 minutes

3. When the beep sounds, assess your productivity

4. Signal your response (click in Waybar or run command):

   taskbeep working  # or wasting
   

5. Take a break or start another session

6. Review your statistics:

   taskbeep stats
   

Installation

cargo install taskbeep

Building

cargo build --release

The binary will be at target/release/taskbeep

Requirements

• Linux system with audio output
• Rust 2024 edition or later
• Audio file: taskbeep.wav in project root