hglass 0.2.0

A terminal-based pomodoro timer with animated ASCII hourglass

hglass

A terminal-based pomodoro timer with an animated ASCII hourglass.

Install

pip install hglass

Or install from source:

git clone https://github.paypal.com/mpushkar/hglass.git
cd hglass
pip3 install -e .

Usage

Single Timer

hglass 25              # 25-minute timer
hglass 5               # 5-minute timer
hglass 0.1             # 6-second test run

If hglass isn't on your PATH after install, use:

python3 -m hourglass.cli 25

Options

hglass 25 --label "Deep Work"      # label above the hourglass
hglass 25 --theme retro            # green-on-black matrix style
hglass 25 --theme light            # light terminal theme
hglass 25 --silent                 # no terminal bell
hglass 25 --no-notify              # no desktop notification

Pomodoro Mode

hglass pomo                                  # 4 rounds, 25min work / 5min break
hglass pomo --work 50 --break 10 --rounds 2  # custom durations
hglass pomo --label "Project X" --theme retro

Controls

Key	Action
Space	Pause / resume the timer
Ctrl+C	Cancel the timer (in pomodoro mode, shows partial summary)

Themes

Theme	Description
dark (default)	Amber sand, sky blue caps — for dark terminals
light	Deep blue caps, dark orange sand — for light terminals
retro	Green-on-black matrix style

Testing

All testing is manual. Quick test commands:

# Basic timer (6 seconds)
python3 -m hourglass.cli 0.1

# Test each theme
python3 -m hourglass.cli 0.1 --theme dark
python3 -m hourglass.cli 0.1 --theme light
python3 -m hourglass.cli 0.1 --theme retro

# Test label
python3 -m hourglass.cli 0.1 --label "Focus Time"

# Test pause — press Space during the timer, press Space again to resume

# Test pomodoro (6s work, 3s break, 2 rounds)
python3 -m hourglass.cli pomo --work 0.1 --break 0.05 --rounds 2

# Test Ctrl+C during pomodoro — should show partial summary

# Test silent mode (no bell, no desktop notification)
python3 -m hourglass.cli 0.1 --silent --no-notify

Features

• Large animated hourglass with falling sand
• Smooth grain-drop neck animation at 8 fps
• Big-digit countdown timer (MM:SS)
• Pause/resume with Space key
• Pomodoro mode with work/break cycles and round tracking
• Desktop notifications on macOS and Linux
• Three color themes (dark, light, retro)
• Bell notification and flashing "TIME'S UP!" on completion
• Automatic fallback for small terminal windows

Requirements

• Python 3.9+
• Rich

License

MIT