A Pomodoro API: the missing piece?

I am periodically a satisfied user of the Pomodoro technique, a time management based on defined timed sessions and breaks.

I tested many Pomodoro applications, and I never really found the one that would fit perfectly my needs.

In this post, I try to identify the main issues with existing Pomodoro applications and I will detail a current project I started.

The current status

There are plenty Pomodoro apps on the market, for all kinds of devices, and/or integrated with well-known applications. A Pomodoro timer integrated as a browser extension? No problem. A Pomodoro application integrated with VIM? It exists too. There are hundreds of Pomodoro applications for any kind of usage.

The main issue with Pomodoro apps is that most (all?) are too linked to your own personal organization.

Often, these Pomodoro apps allow you to define a Todo list, so they can associate your Pomodoro sessions to one specific task.

For some other applications, the Pomodoro sessions are linked to a Project. You defined the list of your projects, and you can start the timer for a particular project.

If I try focusplus.io – an app made by @Xavier_Coiffard – the Pomodoro timer is directly linked to tasks.

The app that I often use – Goodtime Productivity – is linked to projects, which is better for my use-case as I like to track the time allocated to a particular project. In itself, the app is very good. This is for now the most appropriate to my use-case: it’s easy to use, clean, the statistics dashboard is wonderful as it shows the number of sessions or the total time passed on one or all projects, with a nice view of the daily/weekly/month evolution.

This is almost a perfect application (congrats to the developer). But still, I am not fully satisfied.

Dissociated but centralized Pomodoro timer

This is the main issue I have with the existing Pomodoro apps: their lack of flexibility and connectivity.

What I would expect from a Pomodoro app is to use it for a lot of different stuff:

• My Tasks on Notion or Coda
• My projects on another system
• My issues on Github
• Etc.

What I would like to do, is to be able to display the Pomodoro timer everywhere I want: on my mobile, on my desktop, in my browser, in my VIM session, on Notion, Coda, Airtable or Excel.

And this, while keeping the recorded sessions centralized, so I can see the statistics on one unique interface for all my usages.

The data model

Currently, the typical Pomodoro app has the following data model: sessions and total times are linked either to a Task or to a Project.

Therefore, they are already more than a strict Pomodoro timer: you’ll need to define your tasks or your projects, despite you probably have them already elsewhere. This is a big problem.

Instead of this, my perfect Pomodoro application would interface with any kind of external data type that I choose.

But it still lack flexibility. If, in my organization, Tasks are belonging to a Project, I am doomed: If I choose to record the Pomodoro session at the task level, then the statistics about the Project will not be updated.

The most appropriate solution is probably to use a Tag system.

Before starting your session, you just select the correspond tags of this session. If I am working on the “Task 3” of the “Project 1”, I will select the tags “Task 3” and “Project 1” so the working session will be linked to these two entities.

Display your Pomodoro clock everywhere

Currently the Pomodoro timers are either phone applications, browser extensions, standalone applications, or websites.

You can’t display the clock “everywhere”. To achieve that, there are two options:

• You consider this has to be done by the end-user ;
• You tackle the issue with existing techniques.

The first option is not very user-friendly. It’s not a trivial task to develop a GUI of a timer, especially Pomodoro clocks, and more if it has to be synchronized with a backend.

The second option seems better: developping some “clock templates” that can be displayed through an iFrame in most of applications (Coda, Notion, HTML page, and even Google Sheet).

The connectivity to your centralized clock

A centralized Pomodoro clock needs a bi-directional communication. When you click on “Play”, the timer starts, but when your session is finished (usually after 25 minutes), you may need to get the information programatically and not only visually.

Depending of the use-cases, this centralized Pomodoro clock should implement:

• An API, so you can start/pause/stop the clock programatically
• Webhooks, so you can get the events linked to the clock (“session started”, “break started”, “break ended”, “one minute left”, etc.)

With these two weapons, you can cover almost all use-cases.

The implementation

It’s a huge project to implement this. I started a proof-of-concept. It’s basically a web portal where you can configure your “clock instances”, supporting Pomodoro clocks, simple timers and countdowns. Currently, the data model used is not the one with the Tags, but with single Projects. This would change if I continue this project.

Each instance can be configured in details, from the displaying template to the clock parameters.

You can also select the controls that will appear on the clock depending of your needs. If the start/pause/stop features are handled by your own GUI or programatically (or by Notion buttons for instance), you can remove them.

The display can be also tuned to show various informations.

The fun part begins with two next screens: how “Projects” (or Tags) and Sessions are synchronized with the backend. The options should cover a lot of different use-cases depending of what the user wants to do.

For both data (eg Projects/Tags and Time Sessions), you can choose a Push or Pull system.

Example:

Let’s say you want your Pomodoro timer on your Notion page.

Push system: When you click the “synchronize” button of the clock in the iFrame, it will update the selected Notion table. The Pomodoro clock is therefore your trusted source for time sessions and/or Projects/Tags. If you change the data in your Notion table, it will not change the Pomodoro backend.

Pull system: Your Notion tables act as the trusted source. You can modify them manually, click on “Synchronize” button the clock, and all changes made in your Notion table will be reflected in the Pomodoro backend.

Next, we have the Hooks tab, where we can configure the requests done automatically when some events happen. With this feature, you can for instance mark in bold the current project in your Coda page when you change the project on the clock.

Once the configuration is done, your clock is ready to be integrated in your own organization system without any interference. It can be also displayed almost everywhere, and if iFrames are not supported, you can even code your own display.

The nice thing with this system is that it can be used also by developers wanting a fast implementation of a clock and underlying statistics in their app. Let’s say a developer implements a new Todo application. Instead of developing a Pomodoro clock from scratch, he just have to call some APIs to create one clock instance on the fly for each user of his application, show it through an iFrame, and then pull the charts/data to show the statistics.

Current status of this project

This project is on hold for now. The remaining stuff to do is:

• Move from “Projects” to “Tags” as mentioned above ;
• Implement the statistics / charts (accessible via Dashboard, iFrame and API)
• Clock templates to improve. Add vertical templates (for mobile usage).
• Some minor features, like configurable sound at the end of sessions, etc.
• Testing deeply Notion and Coda connectors at least.
• Big effort to do on the documentation and explanations, with tutorials on how to integrate a clock on the main existing applications.

Still a lot of work!