Documentation

How the timer works

Sessions, pauses, breaks and the Pomodoro, the same in the web app, the Mac app and on the iPhone. This page is the reference: if an app does something different, that's a bug.

Sessions

Everything you record is a session: one stretch of work, started with Start and finished with End. The big clock shows the session's time.

A session is made of one or more time entries, and the calendar and invoices use those entries. A session that's never paused or switched has exactly one entry. Pausing stops the entry, and resuming starts a new one. Each new entry carries the session's time so far, so the clock keeps counting from where it was while the gap between entries is never billed.

A session belongs to your account, not to a device. Start on the iPhone and you can pause it on the Mac, resume it in the menu bar and end it in the browser. Every device shows the same session.

Starting

• What it's about. The session screen opens on the project, task and note from your last session, ready to edit before you press Start. Pick another project or task, or a loose to-do, from the line at the top.
• Starting about nothing. Nothing has to be set up first. Pressing Start (or a focus block) with no project or task picked records a Focus session in a project called misc., both made for you the first time and reused after that, so a fresh install can start straight away and move the time later. A session started from the Mac menu bar's Misc. row has no project; you'll be asked what it was about when you pause or end it.
• Starting while something runs. Starting a new session ends the one that's running.

Pausing, breaks and resuming

• Pause stops the running entry and holds the session. The clock stays where it stopped, and a smaller line shows how long you've been paused.
• A break is a pause with an end time. The menu bar's Take a break offers 5, 10, 15 or 30 minutes, and a Pomodoro takes its own breaks. While a break runs the screen says On break and counts down. Once it runs out the screen says Break's over and counts how long ago it ended. A break only resumes the session by itself in a Pomodoro with fixed breaks.
• Resume carries the session on, on the same project and task, its clock continuing.
• A hold lapses after 12 hours. A session paused overnight isn't held the next morning: the next Start begins a new session from zero.

Ending

End finishes the session, whether it's running or paused, and ends any Pomodoro with it. On the iPhone, with calendar access allowed, each entry is added to your calendar as it stops.

Switching project or task mid-session

Picking a different project or task while a session records asks what to do with the time so far:

The Pomodoro

Under the clock are three focus blocks: 30, 45 and 60 minutes. Picking one starts a session the way Start does and adds a plan: focus for that long, then take a break, then repeat. A chime marks each change: a settling pair of notes when a block is up and a rising pair when the break is over. On the iPhone the chime plays even with the ringer on silent, together with a haptic.

• Mid-session. The blocks stay visible while a session without a plan runs. Picking one turns it into a Pomodoro, and the first block counts from the moment you pick it, not from when the session started.
• Counting. While a block runs, the line under the clock counts down to the break, and in the web and Mac apps a ring around the dial fills up.
• When a block is up the app chimes, counts the block as done and puts the session on its break. What the break is depends on your Pomodoro setting.

The break setting

Find it under Settings → Profile → Pomodoro in the web and Mac apps, and under Settings on the iPhone. Each device keeps its own setting, and the default is fixed.

Why the 2 minutes: if a fixed break ended a while ago, for example because the app was closed or the laptop was asleep, you've probably walked away. A timer that restarted by itself would then bill time nobody worked. Instead the app chimes, leaves the session held and shows Break's over until you resume.

Where a Pomodoro runs

The session is shared across your devices, but the Pomodoro plan stays on the device where you picked the focus block. That device keeps the time, chimes and takes the breaks. Every other device sees the result, because pauses and breaks are part of the session. The menu bar shows the pauses and breaks a Pomodoro takes but never runs one.

A plan ends when:

• you press End, or the session ends anywhere else,
• you start a new session, or switch with Restart or Stop and start new,
• the session's hold lapses after 12 hours.

Pausing doesn't end the plan. Resuming always starts a full focus block, even after a pause partway through one.

What the screen says

The word above the clock while a session is going (with no session there is none):

The line under the clock, and the session's details:

For contributors

The web app, the Mac app's window and the iPhone app share one implementation of all of the above. Pure rules (the plan, the next step, the session clock, what a hold is) are in packages/domain/src/session.ts. The device's plan and setting, the Pomodoro driver, the start, switch and end commands and the wording on this page are in packages/sync/src/pomodoro.ts. The apps add only storage, the chime and how errors are shown. Three places mirror parts of it by hand and must be kept in step: the backend (backend/pb_hooks/lib/timer.js), the menu bar's Rust core (apps/desktop/src-tauri/src/domain.rs) and the menu bar's popover (apps/desktop/ui/popover.js).

Next: The calendar