Pomotuimer

A focused, full-screen Pomodoro timer for the terminal.

Pomotuimer keeps the workflow simple: pick a work duration, choose how many work sessions to run, and let the terminal become the timer. It has a large high-contrast display, progress bar, session markers, keyboard controls, and native completion alerts.

No packages, no services, no setup. Just Python and a terminal.

Screenshots

Setup screen:

Running timer:

Features

• Full-screen terminal interface
• Large readable countdown
• Minimal black-and-gold terminal styling
• Distinct calmer break screen
• Built-in setup screen for work, short break, long break, and cycle counts
• Pause, resume, skip, and quit controls
• Desktop notification plus audible alert when a session ends
• macOS, Linux, and Windows alert support where system tools are available
• Plain mode for background runs
• Dependency-free Python script

Usage

./pomotuimer.py

Pomotuimer opens with a setup screen where you can adjust the work duration, short break, long break, number of work sessions, long-break cadence, and alerts.

By default it starts with four 25-minute work sessions, 5-minute short breaks, and a 15-minute long break every fourth work session. The work timer stays the same for each work session.

./pomotuimer.py --cycles 6

Useful options:

./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

Controls

Setup controls:

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

Timer controls:

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

Run ./pomotuimer.py --help for all options.

Alerts

When a session finishes, Pomotuimer rings the terminal bell and tries to show a native notification with sound:

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

Use --no-alert for silent runs.

Skipping a session also sends a short alert unless alerts are disabled.

tmux and background jobs

Pomotuimer works normally inside an attached tmux pane. If you detach tmux, the timer keeps running and notifications still fire when supported by your system.

For true background jobs, use plain mode:

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

Requirements

• Python 3.10+
• An interactive terminal

License

MIT