pomoflow

A Pomodoro timer that runs in your terminal. Start a session, focus on what you need to do, and let pomoflow keep track of the time and your progress.

What is the Pomodoro technique?

You work in focused blocks of time (usually 25 minutes), then take a short break. After a few blocks, take a longer break. The idea is simple: it is easier to stay focused for 25 minutes than to sit down and "study until you're done." pomoflow handles the timing so you only have to focus on the work.

Installation

Requires Python 3.11 or newer.

pip install pomoflow

Or, if you use pipx to keep CLI tools isolated:

pipx install pomoflow

Quick start

# Start a 25-minute session
pomoflow start

# Label the session so you remember what you were doing
pomoflow start --task "Chapter 3 — Calculus"

# Custom duration
pomoflow start --minutes 50

During a session, you will see a live progress bar in the terminal. Press Ctrl+C at any time to stop early. When the session ends, your desktop will show a notification and the terminal will ring a bell.

All commands

start — begin a focus session

pomoflow start
pomoflow start --task "Physics revision"
pomoflow start --minutes 45 --task "Essay draft"

config — adjust your default durations

# See current settings
pomoflow config

# Change the default session length
pomoflow config --pomodoro 50

# Change break lengths
pomoflow config --short-break 10 --long-break 20

# Go back to defaults
pomoflow config --reset

history — see your recent sessions

pomoflow history

# Show more entries
pomoflow history --limit 20

stats — see how you have been doing

# Summary for the last 7 days
pomoflow stats

# Last 30 days
pomoflow stats --days 30

Shows total sessions, total focus time, completion rate, current streak, and a per-day breakdown.

Data

pomoflow saves your sessions and config to ~/.pomoflow/. Nothing is sent anywhere.

~/.pomoflow/
├── history.json   # session log
└── config.json    # your preferences

Development

git clone https://github.com/guialmm/pomoflow.git
cd pomoflow
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install --hook-type commit-msg
pre-commit install

Run tests:

pytest

Contributing

See CONTRIBUTING.md.

Changelog

See CHANGELOG.md.

License

MIT — guialmm