Pomodoro timer and session planner

What this works out

A pomodoro session is not a timer, it is a sequence: work, break, work, break, and a longer break at the end of each set. The question people actually have is what that sequence costs — how much of the afternoon it takes, how much of it is work rather than rest, and what time it puts you at the other end.

That is arithmetic, and it is easy to get wrong in the direction that matters. Eight pomodoros sounds like three hours and twenty minutes of work, and it is, but it occupies four hours and five minutes of the day. This publishes the whole plan before the first interval starts, so the collision with the meeting at one o’clock is visible now rather than at one o’clock.

The method

Three decisions in the formula are worth stating, because a reasonable person would guess at least one of them the other way.

The break belongs after the pomodoro, and the last one has none. Breaks are counted between pomodoros, so N pomodoros give N - 1 breaks and 2N - 1 intervals in total. Scheduling a break after the final pomodoro would add time to the session that nobody spends in it.

The long break replaces the short one. At the end of a set — every R-th pomodoro — the break that would have been short is long instead. It is not appended to a short break, so a set of four costs one long break, not one of each. With N = 8 and R = 4 the long break falls after the fourth pomodoro and not after the eighth, because the eighth is the last one and gets no break at all.

Clock times are integer arithmetic, not dates. Minutes since midnight, added, then divided by 1,440 for the day and the remainder for the face. Parsing 09:00 into a Date would attach it to today, in the host timezone, with whatever daylight-saving transition that day happens to carry — three ways for the same input to produce two different answers on a page whose whole claim is that the arithmetic is checkable. A session that runs past midnight is labelled (next day) rather than being wrapped silently, because five past one tonight and five past one tomorrow morning are not the same answer.

The cue at the end of each interval is a short tone synthesised with the Web Audio API rather than a sound file, so nothing is downloaded and nothing is requested when it plays. The countdown reads the clock rather than counting its own ticks, which is why a throttled background tab delays when the end of an interval is noticed but does not make the timer slow.

Before you read on

Eight pomodoros, with a long break every fourth. How many long breaks does the session contain?

• ATwo — eight pomodoros is two complete sets.

  Two sets, but only one of them is followed by anything.

• BOne.

  Yes: after the fourth. The eighth is the last one and gets no break at all.

• COne long and one short, since the set ends and the session does too.

  The long break replaces the short one rather than being added to it — and after the eighth there is neither.

One, after the fourth pomodoro. Breaks are counted between pomodoros, so eight give seven breaks and fifteen intervals in total; of those seven, floor(7 / 4) = 1 is long. Scheduling a break after the final pomodoro would add fifteen minutes to a session nobody spends in it. Both halves of that catch people out — a reasonable person would guess at least one of them the other way.

• Focus20081.6%
• Break4518.4%

A worked example

Twenty-five-minute pomodoros, five-minute short breaks, a fifteen-minute long break, sets of four, eight pomodoros, starting at 09:00.

 1  Focus         25 min   09:00    25 elapsed
 2  Short break    5 min   09:25    30
 3  Focus         25 min   09:30    55
 4  Short break    5 min   09:55    60
 5  Focus         25 min   10:00    85
 6  Short break    5 min   10:25    90
 7  Focus         25 min   10:30   115
 8  Long break    15 min   10:55   130
 9  Focus         25 min   11:10   155
10  Short break    5 min   11:35   160
11  Focus         25 min   11:40   185
12  Short break    5 min   12:05   190
13  Focus         25 min   12:10   215
14  Short break    5 min   12:35   220
15  Focus         25 min   12:40   245

Checked against the closed form: seven breaks, of which floor(7 / 4) = 1 is long, so 6 x 5 + 1 x 15 = 45 minutes of break against 8 x 25 = 200 minutes of focus. The session is 245 minutes and finishes at 09:00 + 4h 05m = 13:05.

These are the same numbers asserted in this tool’s test file, so if the formula ever changes without this page changing with it, the build fails.

What it does not do

It does not model the session you will actually have. It assumes no interruption, no pomodoro abandoned halfway, no break that runs long, and no task that finishes early — and every one of those moves the finish time later except the last. Cirillo’s own method spends as much attention on recording interruptions as on the timer, and none of that is here.

It does not know about your calendar, so it will happily plan a session straight through a meeting. It keeps no history: close the tab and the plan and the countdown are both gone, because there is nowhere for them to be kept. And it takes no position on whether twenty-five minutes is the right length for you — that number comes from the technique as published, not from anything measured about your work.

Given
  F  minutes in one pomodoro
  S  minutes in a short break
  L  minutes in a long break
  N  pomodoros in the session
  R  pomodoros in a set

the session is 2N - 1 intervals:

  interval 2k - 1  =  pomodoro k                  for k = 1 … N
  interval 2k      =  the break after pomodoro k  for k = 1 … N - 1
                        long   when k mod R = 0
                        short  otherwise

There is no break after pomodoro N.

  longBreaks  = floor((N - 1) / R)
  shortBreaks = (N - 1) - longBreaks

  focusTime = N x F
  breakTime = shortBreaks x S + longBreaks x L
  totalTime = focusTime + breakTime

Clock times are whole minutes since midnight:

  start     = 60 x hour + minute
  finish    = start + totalTime
  clockFace = finish mod 1440
  daysLater = floor(finish / 1440)