taskbeep-0.1.15 is not a library.

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)
Run custom scripts on timer finish (for notifications, popups, automation)

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:

Run in the background for the specified interval
Play a beep sound when the interval completes
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

Start your work session:

taskbeep start "Implement new feature" 1500

Work on your task for 25 minutes
When the beep sounds, assess your productivity
Signal your response (click in Waybar or run command):
```
taskbeep working  # or wasting
```
Take a break or start another session
Review your statistics:
```
taskbeep stats
```

Configuration

TaskBeep can be configured via a TOML configuration file located at ~/.config/taskbeep/config.toml

Configuration Options

session_duration: Default session duration in seconds (default: 1500 / 25 minutes)
volume: Audio volume from 0.0 to 1.0 (default: 0.4)
beep_frequency: Beep sound frequency in Hz (default: 2048.0)
first_beep_duration: First beep duration in seconds (default: 0.08)
second_beep_duration: Second beep duration in seconds (default: 0.12)
gap_duration: Gap between beeps in seconds (default: 0.09)
pause_duration: Pause after beep pattern in seconds (default: 0.7)
on_timer_finish: Optional script to run when the timer finishes

Script Execution on Timer Finish

You can configure a script to run automatically when the timer finishes (after the beep). This is useful for:

Showing custom notifications
Displaying interactive prompts (e.g., with rofi, fuzzel, dmenu)
Logging session information
Automating the working/wasting response

Add this to your config.toml:

on_timer_finish = "/path/to/your/script.sh"

The script receives these environment variables:

TASKBEEP_TOPIC: The current task topic
TASKBEEP_DURATION: Session duration in seconds
TASKBEEP_SESSION_COUNT: Number of completed sessions (including the current one)

Security

Scripts run with your user privileges. TaskBeep validates:

The script path must be absolute (e.g., /home/user/.config/taskbeep/script.sh)
The script must exist and be executable (chmod +x script.sh)

Only configure scripts you trust.

Example Scripts

The repository includes ready-to-use example scripts in the examples/on_beep/ directory:

Interactive Prompts:

rofi_prompt.sh
fuzzel_prompt.sh
wofi_prompt.sh
zenity_prompt.sh

Other Examples:

notify_only.sh
log_session.sh
motivational_messages.sh

See the examples/on_beep directory for more details and usage instructions.

The examples/waybar/ directory is available for Waybar integration examples.

Quick setup:

# Copy the script you want
cp examples/on_beep/rofi_prompt.sh "$HOME/.config/taskbeep/timer_finish.sh"
chmod +x "$HOME/.config/taskbeep/timer_finish.sh"

# Configure in ~/.config/taskbeep/config.toml
echo "on_timer_finish = \"$HOME/.config/taskbeep/timer_finish.sh\"" >> "$HOME/.config/taskbeep/config.toml"

Managing Configuration

# Show configuration file path
taskbeep config --path

# Reset configuration to defaults
taskbeep config --reset

# View current configuration
cat $(taskbeep config --path)

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

taskbeep 0.1.15