Here’s a side project I’ve been working on for the last months:

Pomoglorbo is a text user interface (TUI) based productivity timer for studying, working, and all other activities that require you to focus for long periods of time. Pomoglorbo has been forked from pydoro. The Pomoglorbo timer runs in your terminal, is lightweight, supports many environments, and can even be run over SSH.

What is the Pomodoro Technique?

Using the Pomodoro Technique, you can structure your work into short phases of work with short breaks in between them. Typically, a Pomodoro, the smallest unit of work, is 25 minutes long, and is followed by a 5 minute break. After doing this for four times, a longer break follows. The most common pattern of doing Pomodoros is:

1. 25 minutes work
2. 5 minutes short break
3. 25 minutes work
4. 5 minutes short break
5. 25 minutes work
6. 5 minutes short break
7. 25 minutes work
8. 20 minutes short break
9. Go back to 1.

Another essential part of the Pomodoro technique is deciding what to do during each Pomodoro and never starting one without a plan. It is useful to break apart work so that the elements fit neatly within a single Pomodoro. This is somewhat similar to techniques like time boxing in Agile development.

How to use Pomoglorbo for Pomodoros

Pomoglorbo is a CLI based application, and it requires basic knowledge of how to install Python packages on your computer.

Pomoglorbo is distributed as a package on PyPI. The easiest way to get started is by installing the pip package using a tool like pipx. See the previous link for instructions on how to install it on macOS, Linux, Windows, and so on. If you have any problems installing Pomoglorbo on your system, contact me using the email address at the bottom of this page.

Once you have pipx on your computer, you can install and run Pomoglorbo using the following command:

pipx install pomoglorbo

After running this, you will see something like the following output:

  installed package pomoglorbo 2024.6.18.post2, installed using Python 3.11.9
  These apps are now globally available
    - pomoglorbo
⚠️  Note: '/Users/justusperlwitz/.local/bin' is not on your PATH environment variable. These apps will not be
    globally accessible until your PATH is updated. Run `pipx ensurepath` to automatically add it, or manually
    modify your PATH in your shell's config file (i.e. ~/.bashrc).
done! ✨ 🌟 ✨

If you have set up your PATH variable correctly, you can now run it by running pomoglorbo, or you can also try:

pipx run pomoglorbo

You will see the initial screen from the screenshot at the beginning of this post. Now, you can start your first Pomodoro by making sure that <Start> is selected using the arrow keys and then pressing enter. Of course, you can adjust the configuration to your liking. All available configuration variables can be found in the Repository config.py file

A sample configuration file can be found here.

By default, Pomoglorbo searches for the configuration file in your XDG_CONFIG_HOME under pomoglorbo/config.ini, which for many people will be something like this:

# $HOME is the path to your home folder
$HOME/.config/pomoglorbo/config.ini

Got any questions about Pomoglorbo configuration? Feel free to send me an email!

Try installing Pomoglorbo as a Nix flake

Pomoglorbo is also available as a Nix flake. You can look at my home nix configuration here to see how I have configured Pomoglorbo to be installed as a Nix flake.

Pomoglorbo and pydoro

As mentioned in the beginning, Pomoglorbo has been forked from the original MIT-licensed pydoro last year. I like that pydoro uses Click, to build the TUI and having command line hooks that can be configured in a configuration .ini file. On the other hand, I wanted to have more configurability for CLI arguments, and the UI used up a lot of space in my terminal.

I have also used this as an opportunity to rewrite the original OOP based UI with Python dataclasses, and have added rigorous Mypy base type checking. I have modeled Pomoglorbo as a state machine, and used Python’s new match expressions to make sure that no invalid state transition can happen. Timer software with different state transitions are a perfect use case for implementing state machines.

During the rewrite, most of the original code has been rewritten, but many parts, especially the design are very similar to pydoro. If you would like to try out the original version, give pydoro a try.