# hglass

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

## Install

```bash
pip install hglass
```

## Usage

### Single Timer

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

```bash
python3 -m hourglass.cli 25
```

### Options

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

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

```bash
# 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](https://github.com/Textualize/rich)

## License

MIT
