Flowkeeper

Flowkeeper is a Pomodoro timer, which stays as close as possible to Pomodoro Technique description found in the original book by Francesco Cirillo. Featuring classic UI paradigm (desktop-first, no Electron), keyboard shortcuts and advanced settings, Flowkeeper is optimized for power users.

Visit flowkeeper.org for screenshots, downloads and FAQ.

If you used it, I will appreciate it if you take a minute to provide some feedback. Your constructive criticism is welcome!

Building

Flowkeeper has a single major dependency -- Qt 6.11, which in turn requires Python 3.10 or later.

Building for Linux and macOS

On some lean distributions like a minimal installation of Debian 12, you might need to install libxcb-cursor0 first, e.g.

sudo apt install libxcb-cursor0

Create a virtual environment and install dependencies:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Note that requirements.txt contains ALL libraries and tools needed to run, test and create installers. You can use requirements-run.txt if you only want to debug Flowkeeper locally, or requirements-build.txt if you also want to create distributable / portable bundles.

Then you need to "generate resources", which means converting data files in /res directory into the corresponding Python classes. Whenever you make changes to files in /res directory, you need to rerun this command, too:

build/common/generate-resources.sh

From here you can start coding. If you want to build an installer, refer to the CI/CD pipeline in .github/workflows/build.yml. For example, if you want to build a DEB file, you'd need to execute pyinstaller installer/normal-build.spec and then ./package-deb.sh.

If you see this error:

No QtMultimedia backends found. Only QMediaDevices, QAudioDevice, QSoundEffect, QAudioSink, and QAudioSource are available.

then install libatomic1:

sudo zypper install libatomic1

Building for Windows

Consult the above section for details. In short, install Python 3.11. Then:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Generate resources:

cd res
pyside6-rcc --project -o resources.qrc
pyside6-rcc -g python resources.qrc -o "../src/fk/desktop/resources.py"

Package as a distributable / portable bundle (OPTIONAL):

pyinstaller installer\portable-build.spec
pyinstaller installer\normal-build.spec

Testing Flowkeeper

To execute Flowkeeper:

PYTHONPATH=src python -m fk.desktop.desktop

To run unit tests w/test coverage (install requirements from requirements.txt or requirements-test.txt first):

PYTHONPATH=src python -m coverage run -m unittest discover -v fk.tests
python -m coverage html

To execute end-to-end tests:

PYTHONPATH=src python -m fk.desktop.desktop --e2e

Technical details

• Design considerations
• Data model
• Strategies
• Events
• UI actions
• CI/CD pipeline
• Building for Alpine Linux
• Building for FreeBSD

Copyright

Copyright (c) 2023 - 2026 Constantine Kulak.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.