Pomodoro CLI

A command-line Pomodoro timer with progress tracking, desktop notifications, and session history.

Features

• Interactive mode with preset options
• Command-line flags for quick start
• Progress bar with countdown display
• Desktop notifications with sound
• Session tracking and statistics
• Streak tracking

Installation

# Clone or navigate to the project directory
cd POMODORO

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e .

System Requirements

• Python 3.10+
• notify-send (for desktop notifications)
• paplay (for notification sounds, optional)

On Debian/Ubuntu:

sudo apt install libnotify-bin pulseaudio-utils

Usage

Interactive Mode

Simply run without arguments:

pomodoro

You'll see a menu to select presets or customize your session:

Pomodoro Timer

Select a preset or customize:
  1  25/5   - Classic (25 min work, 5 min break)
  2  50/10  - Extended (50 min work, 10 min break)
  3  15/3   - Short (15 min work, 3 min break)
  4  Custom

Choice [1-4]: _

Command-Line Flags

# Classic 25/5 with 4 repetitions
pomodoro -w 25 -b 5 -r 4

# Extended 50/10 with 2 repetitions
pomodoro -w 50 -b 10 -r 2

# Quick 15/3 with 6 repetitions
pomodoro -w 15 -b 3 -r 6

View History & Stats

# View session history
pomodoro --history

# View detailed statistics
pomodoro --stats

All Options

Usage: pomodoro [OPTIONS]

Options:
  -w, --work INTEGER RANGE    Work duration in minutes (1-120)
  -b, --break INTEGER RANGE   Break duration in minutes (1-60)
  -r, --reps INTEGER RANGE    Number of pomodoro cycles (1-20)
  --history                   Show session history
  --stats                     Show detailed statistics
  --version                   Show the version and exit.
  --help                      Show this message and exit.

Timer Display

During a session, you'll see a progress bar with countdown:

╭──────────────────────────────────────────────────────────╮
│ Pomodoro Timer - Session 2/4                             │
│                                                          │
│ WORK TIME ████████████████████░░░░░░░░░░░░░░░░░░░░ 52%   │
│                                                          │
│   ⏱  12:18 remaining                                     │
│                                                          │
│   Press Ctrl+C to cancel                                 │
╰──────────────────────────────────────────────────────────╯

Data Storage

Session data is stored in XDG-compliant location:

~/.local/share/pomodoro/sessions.json

License

MIT