Pomotuimer

A dependency-free, full-screen Pomodoro timer for the terminal.

Pomotuimer turns the current terminal into a large, high-contrast focus timer. Choose the work duration and cycle count, press Enter, and control the session without reaching for a browser or creating an account.

Features

• Full-screen terminal interface with a large countdown and progress bar.
• Configurable work, short-break, long-break, and cycle durations.
• Pause, resume, skip, and quit controls.
• Distinct work and break screens.
• Native completion notifications and sound where the operating system supports them.
• Plain mode for tmux, detached sessions, and background jobs.
• No Python packages, services, accounts, or network calls.

Run

git clone https://github.com/wtbates99/pomotuimer.git
cd pomotuimer
./pomotuimer.py

Python 3.10 or newer and an interactive terminal are required.

Useful examples:

./pomotuimer.py --cycles 6
./pomotuimer.py --work 50 --break 10 --cycles 2
./pomotuimer.py --work 0.1 --break 0.1 --cycles 1 --label "Writing"
./pomotuimer.py --plain --work 25 --cycles 4
./pomotuimer.py --no-alert

Run ./pomotuimer.py --help for every option.

Controls

Setup:

Up / Down     select a setting
Left / Right  adjust the selected setting
Space         toggle alerts when Alerts is selected
Enter         start
Q / Esc       quit

Timer:

Space / P  pause or resume
S          skip the current session
Q / Esc    quit

Alerts

Pomotuimer rings the terminal bell and attempts a native notification:

• macOS: osascript and an available system sound.
• Linux: notify-send plus canberra-gtk-play, paplay, or aplay when available.
• Windows: the standard notification sound through winsound.

Use --no-alert when notifications are not wanted. Alert support depends on the host terminal and operating-system utilities.

tmux and background jobs

The timer continues inside a detached tmux session. For a noninteractive background job, use plain mode:

./pomotuimer.py --plain --work 25 --cycles 4 &

Validation

python -m py_compile pomotuimer.py
./pomotuimer.py --help
./pomotuimer.py --plain --work 0.01 --break 0.01 --cycles 1 --no-alert

License

MIT © 2026 William Bates.