Flowkeeper v0.10.0

March 15, 2025

This version brings Flowkeeper even closer to the original Pomodoro Technique definition from Francesco Cirillo's book. Pomodoro interruptions are now handled as the book prescribes, and there is finally support for long breaks. One major deviation from the Technique in this version is the ability to track unfocused time. As usual there's a bunch of quality-of-life improvements, bugfixes and better support for Linux.

← What's new in v0.9.1

Pomodoro by the Book

I realized that what makes Flowkeeper better than other timers is that it sticks to Pomodoro Technique as Francesco Cirillo described in his book. And so I bought the latest edition, read it from A to Z, and tried to adjust Flowkeeper behavior to match it as closely as possible. Here are some of the notable deviations:

The Book	Flowkeeper
You apply Pomodoro for "organizational activities" like meetings, emails and calls	You don't estimate such activities in pomodoros and track them as unfocused time instead (see below)
Pomodoro is marked completed when it rings, before its short break starts	Pomodoro is marked completed when its short break ends
Short breaks are flexible, minimum 3 -- 5 minutes, up to 10 minutes	All short breaks have the same fixed duration (5 minutes by default)
Long breaks last 15 to 30 minutes (count down)	Long breaks can last indefinitely (count up)
If you finish work within the first 5 minutes, just ignore it and start next pomodoro	You'd have to void such pomodoro
There are two task lists -- To Do Today and Activity Inventory	There are Backlogs, which serve all planning purposes
You track pomodoro statistics using Records Sheet	You use a combination of Pomodoro Health and Work Summary
You specify activity type, e.g. "Writing" or "Condensing"	You use tags like #writing or #condensing
You differentiate between internal and external interruptions by using different marks (' and -)	You can provide reasons for interruptions, which all produce the same ' marks
Schedule / calendar takes precedence over Pomodoro	Scheduling is not supported (yet)
You highlight the third estimate for retrospective purposes	Only the second estimate is displayed differently from the first
Pomodoro timer produces two types of sounds -- it ticks and rings	Flowkeeper timer ticks, rings and plays music during short breaks

Tracking unfocused time

Some activities are not compatible with Pomodoro Technique, or simply do not require deep focus. At the same time, stuff like calls and meetings steals your productivity, so you'd still like to track those, just to know how much damage they do.

Try to start a work item with no pomodoros -- this will automatically make it a time tracker.

In Tracking mode Flowkeeper counts time up rather than down. You still get your progress indicator, but it functions as a wall clock rather than a kitchen timer.

You can start / stop / restart tracking via Ctrl-S / ⌘-S.

You can't mix focused (Pomodoro) and unfocused time tracking on the same work item. Also, unfocused time is not counted in Pomodoro Health (F9). Otherwise those Tracker items behave just like the normal Pomodoro ones. For example, they show up in the Work Summary (F3) and can be completed.

^{GitHub Issues:
#94,
#98}

Long breaks

Pomodoro Technique defines two types of breaks. The short ones keep you focused while you work on one task, while the long ones allows you to relax and help switching between tasks.

Until now Flowkeeper only supported short breaks, ensuring that you are getting some minimal amount of rest between pomodoros needed for switching between focused and diffused thinking modes. And then it was up to you to decide when you need to take a longer break.

In v0.10.0 Flowkeeper suggests you taking a long break after four completed pomodoros, as the Book prescribes.

Unlike short breaks the long ones don't have predefined duration, and thus Flowkeeper displays elapsed time, not remaining. There's no music during long breaks. To end a break, you press Ctrl-S / ⌘-S, or click "Stop Tracking Time".

^{GitHub Issues:
#53}

Working in series

Some Flowkeeper users prefer their Pomodoro fully automated, i.e. next Pomodoro starting automatically after the short break ends. In this version it is implemented as an optional feature, which is disabled by default.

The series stops if

There are no more startable pomodoros in the current work item,
You voided a Pomodoro,
A long break started.

To enable working in series, go to Settings (F10) > Series and breaks.

^{GitHub Issues:
#53}

Moving items between backlogs

If you select a backlog and press Ctrl-M / ⌘-M, Flowkeeper will create a new backlog with a copy of incomplete work items from the one you selected.

In addition to that, v0.10.0 also implements a way to move work items between backlogs. To move an item, just drag it to a different list.

It is useful for filling your daily task list with items from global backlogs, or to finish something you couldn't complete yesterday. This feature makes planning a breeze.

^{GitHub Issues:
#60}

Recording interruptions

Avoiding interruptions is the key aspect of Pomodoro Technique. The Book is very prescriptive about recording interruptions and doing retrospective analysis on those.

Starting with v0.10.0 there's a new "Record Interruption" action when you click the timer widget or press Ctrl-T / ⌘-T. It allows you enter an optional note, and leaves a subtle tick mark ' next to the current Pomodoro.

Voiding a Pomodoro records an interruption automatically.

^{GitHub Issues:
#75,
#92}

Import from GitHub [Beta]

Import from GitHub Issues is now available by pressing Ctrl-I / ⌘-I. It supports both public and private repositories.

When you import from GitHub, you can choose to import metadata like assignee or issue state as #tags, so that you can filter by issue labels, for example.

It is important to understand how consecutive imports merge with existing data:

Import creates a backlog with the name corresponding to GitHub org/repo, e.g. "flowkeeper-org/fk-desktop". If this backlog already exists, Flowkeeper will try to merge imported data with its content.
If it finds a work item that starts with "[id] - [title]", it will consider it the same item. It will rename it, if you chose a different set of tags during the import, but it will not delete this item or create a duplicate. So, if you tracked some time or done some pomodoros on this item -- those will stay.
It will create new items which don't exist yet.
It won't touch completed items (they are sealed and can't be renamed anyway), and it will never delete anything.

If you execute it against some large repository like facebook/react, this import will push Flowkeeper to its limits, mainly because of hundreds of new tags. If you uncheck tags creation or disable tags altogether in Settings > General > Display #tags, Flowkeeper will handle even thousands of tasks without breaking a sweat.

^{GitHub Issues:
#125}

Import from CSV [Beta]

Import from CSV is now available by pressing Ctrl-I / ⌘-I. You can choose the field delimiter, as well as specify that your CSV has headers. The CSV file must have three columns -- backlog name, work item name, and work item state ("new" or "completed").

It is important to understand how consecutive imports merge with existing data:

Import creates backlogs corresponding to the first column in the file. If a backlog with this name already exists -- it will be reused.
If it finds an existing backlog / work item combination, it will leave it as-is, except if you marked it as completed in the CSV file -- then it will complete the corresponding item in Flowkeeper.
If you rename something in the CSV and re-import, Flowkeeper will create new items. It won't rename existing items. If you delete rows from CSV, the import will simply ignore it.
It won't touch completed items (they are sealed and can't be renamed anyway), and it will never delete anything.

^{GitHub Issues:
#125}

Detailed tooltips

Hover your mouse over pomodoros to see the detailed log of your work. We'll see how to visualize it better in the upcoming versions.

^{GitHub Issues:
#93}

Flowkeeper on Flathub

Starting with v0.10.0 you can install Flowkeeper from Flathub, both for x86 and ARM architectures:

$ flatpak install flathub org.flowkeeper.Flowkeeper
$ flatpak run org.flowkeeper.Flowkeeper

The application is securely sandboxed and works through XDG Desktop Portals, which was tested on GNOME and KDE. On Flatpak-friendly distros like openSUSE you can also find it in KDE Discover.

One great thing about Flatpak is that it will keep your Flowkeeper up to date.

^{GitHub Issues:
#63}

OpenSUSE repository

Thanks to the awesome openSUSE Build Service I can now provide Flowkeeper repos for most of the mainstream Linux distributions, starting with openSUSE Tumbleweed. To install Flowkeeper execute:

$ zypper addrepo https://download.opensuse.org/repositories/home:
/flowkeeper/openSUSE_Tumbleweed/home:flowkeeper.repo
$ zypper install flowkeeper

Support for Debian, Ubuntu and Fedora repos is coming soon! It will become the recommended way to install Flowkeeper on Linux.

^{GitHub Issues:
#127}

Flowkeeper CLI [Beta]

All Flowkeeper installers now bundle fk binary, which you can use to query and modify Flowkeeper file database. As of v0.10.0 it only works with Backlogs.

Try fk backlog --help to see what you can do with it. The most impressive results can be obtained by enabling file watching in Flowkeeper (Settings (F10) > Connection > Watch changes). Then, every time you make a change via CLI, your running Flowkeeper application will pick it up immediately.

It is still in experimental state and is not added to the PATH automatically. In the future releases I shall extend its functionality to support work items, timer state, import/export, statistics, and more.

^{GitHub Issues:
#46}

Miscellaneous improvements

Some of the improvements are less visible, yet they still took some time to implement, so let's list them here:

There are new Linux binaries for ARM / aarch64.
AppImage fat binary is now available for download.
Standard Linux / Windows / macOS directories for data files and logs are now used by default for all new installations.
New font selector for macOS, which supports Apple system font.
Flowkeeper window now hides automatically on auto-start.
Added support for the latest Qt 6.8.x.
Performance improvements.
Updated documentation in GitHub.
Unit test code coverage increased to 90%.
Complete drag & drop rewrite provides smoother user experience.

^{GitHub Issues:
#65,
#102,
#113,
#130}

Bugfixes

Last but not least, I fixed all bugs from GitHub Issues I could reproduce:

Selecting directory as log file.
Window icon on Wayland.
Line breaks in work items and backlogs.
Changing audio devices while Flowkeeper is running.

^{GitHub Issues:
#108,
#110,
#120,
#132}

[1] Pomodoro® and Pomodoro® Technique are registered trademarks of Francesco Cirillo. Flowkeeper is an independent and unofficial implementation. It is neither affiliated nor endorsed by the Pomodoro® Technique authors.