---
name: timer-cli
description: Terminal countdown timer + Pomodoro mode with macOS notifications and optional sound. Accepts natural durations like `25m`, `1h30m`, `45s`. Lock-screen-safe (uses osascript notify), optional `--say "TIME"` voice announcement, optional `--terminal-bell` audio cue. Pomodoro mode runs alternating focus/break cycles with progress bar in terminal. Pure stdlib + macOS native. Use when the user asks for a timer, countdown, pomodoro, focus session, "remind me in N minutes", egg timer, or stopwatch.
---


# timer-cli

## Single timer

```bash
python3 ~/.claude/skills/timer-cli/scripts/timer.py 25m
# countdown bar in terminal, macOS notification when done
```

```bash
python3 ~/.claude/skills/timer-cli/scripts/timer.py 1h30m --label "render export"
# label shown in the bar + final notification
```

## Voice announcement

```bash
python3 ~/.claude/skills/timer-cli/scripts/timer.py 5m --say "tea ready"
# uses macOS `say` to speak when done
```

## Pomodoro

```bash
python3 ~/.claude/skills/timer-cli/scripts/timer.py --pomodoro
# default: 4 cycles of 25min focus + 5min break, then 15min long break
```

```bash
python3 ~/.claude/skills/timer-cli/scripts/timer.py --pomodoro --focus 50m --break 10m --cycles 3
# custom intervals
```

## Stopwatch (count up)

```bash
python3 ~/.claude/skills/timer-cli/scripts/timer.py --stopwatch
# Ctrl-C to stop and print total elapsed
```

## Flags

- positional: duration string (e.g., `25m`, `1h30m`, `45s`, `90`) — defaults to seconds if no unit
- `--label` — text shown in the timer bar + notification
- `--say` — text to speak via macOS `say` when timer ends
- `--terminal-bell` — emit terminal bell every second of the last 10s
- `--no-notify` — skip the macOS notification
- `--sound` — system sound name (default `Glass`; `Funk`, `Hero`, `Ping`, etc — see `/System/Library/Sounds/`)
- `--pomodoro` — run pomodoro mode
- `--focus` — pomodoro focus duration (default `25m`)
- `--break` — pomodoro break duration (default `5m`)
- `--cycles` — pomodoro cycles before long break (default `4`)
- `--long-break` — long-break duration (default `15m`)
- `--stopwatch` — count up instead of down

## Output

Live terminal progress bar:
```
 [████████████░░░░░░░░░░░░] 12:34 / 25:00  focus #2
```

macOS notification on completion. Optional voice + sound.