TomatoTimer User Manual

Installation

Web app

Go to tomatotimer.sovkit.com
Start using it right away — no sign-up required
Choose Install app from your browser menu (Add to Home Screen on mobile) to open it as a standalone app

Browser extension

Available on the Chrome Web Store, Firefox Add-ons, and Edge Add-ons, with other browsers to follow. The extension offers exactly the same features as the web app; wherever the two behave differently, the sections below say so.

Running a pomodoro

The home page centres on a single dial showing the current status and the time left, with two buttons below it.

Click Start, and the ring fills clockwise from the top in the theme colour while the status reads "In progress"
The button becomes Pause; the elapsed portion turns dark grey and the remaining time freezes in place
Click Resume to continue. Once the session ends, the button returns to Start
Abandon is greyed out while the timer is idle. Clicking it discards the current session

The moment a session ends, a reminder notification appears. The ring fills completely and immediately resets to grey, ready for the next round.

By default, TomatoTimer schedules no breaks and never starts the next pomodoro for you — when to begin is entirely your call.

Adjusting the length on the fly

The − and + buttons on either side of the dial take off or add 5 minutes at a time. They only affect the current run and leave your Features settings untouched:

Before you start, they change the length of the next pomodoro only
While a session is running or paused, they change the current session; with pomodoros in a row turned on, the rest of the run keeps the adjusted length too
Once the run is over, the next one starts with the length set in Features again

The length cannot go beyond the range Features allows, and at least 1 minute of the current session must remain after an adjustment. When a limit is reached, the matching button is greyed out.

Keyboard shortcut (browser extension)

Press the TomatoTimer shortcut to start, pause, or resume the timer without opening the side panel; the reading on the extension icon updates accordingly. The current keys are shown on the Start/pause shortcut row under Features, and clicking them takes you to your browser's shortcuts page to change them. In Firefox, open about:addons, click the gear icon, and choose Manage Extension Shortcuts.

Breaks and back-to-back rounds

Both are off by default and can be turned on under Features:

Break length — set it to 1–30 minutes, and every pomodoro moves straight into a break when it ends: the ring turns green and the status reads "On a break". You are reminded again when the break is over
Pomodoros in a row — set it to 2–12, and a single click on Start runs that many pomodoros back to back. Each one starts on its own, and the dial shows which one you are on below the time; click that count to jump straight to this setting. After the last one (and the break that follows it), the timer returns to idle

Breaks can be paused too, and Abandon becomes Skip break: clicking it starts the next pomodoro straight away, and the count carries on. Skipping the break after the last pomodoro completes the run. Clicking Abandon during a pomodoro ends the whole run.

Break time never counts as focus time. Changes to either setting made after you click Start take effect the next time you start.

Focus statistics

Only completed sessions count, and each one counts for its full configured length. Abandoned sessions add neither a count nor any time, and paused stretches never count as focus time. A session that crosses midnight is recorded on the day it started. With syncing on, the records from all your devices are counted together.

Today

The row at the top of the home page shows how many pomodoros you have completed today and your focus time, with your current streak of focus days on the right. A day counts towards the streak as soon as you complete one pomodoro. If you have not completed one yet today, the streak is counted from yesterday, so it is never broken before the day is over.

Statistics card

The statistics card at the bottom of the home page switches between three ranges in its top-right corner — 7d, 30d, and All (Pro) — and its six figures change accordingly:

Pomodoros and Focus time — the totals for the range
Active days — the number of days in the range with a completed pomodoro
Daily avg. — focus time averaged over every day in the range, including days without any focus; for All, counting starts from the day of your first record
Best streak — the longest run of consecutive focus days in the range
Peak day — the day of the week with the most focus time in the range

Below them, a heatmap shows your focus for each day of the last six months. Each column is a week running from Monday to Sunday, the colour deepens with more focus time, and today's cell is outlined. Point at or tap a cell, and the line at the bottom shows that day's pomodoros and focus time; otherwise that line shows a playful comparison, such as how many movies the focus time in the range adds up to.

Daily focus goal (Pro)

Set Daily goal in Features to any number from 1 to 20, and the right side of the Today row at the top of the home page switches to a goal progress bar, comparing today's completed count against your goal. The figure switches to the theme colour once you reach it. Anything beyond the goal is still shown in full rather than hidden.

Set it to 0 for no goal, and that spot goes back to showing your streak of focus days.

Exporting statistics (Pro)

Click the download button next to the statistics card's title to export your daily pomodoro counts and focus minutes as a file. Only days with a completed pomodoro are included. Choose the format under Features:

CSV — the default, opens directly in Excel, Numbers, or any other spreadsheet app
JSON — suits scripts and other tools

Reminders

A system notification arrives the moment a pomodoro or a break ends, even when the panel is closed. Each new reminder replaces the previous one, so your notification centre only ever holds the latest.

Browser extension — clicking the notification opens the side panel, except on Firefox, where only the toolbar icon can open the sidebar
Web app — your browser asks for notification permission the first time you click Start; reminders only work once you allow it. If permission is denied, the app tells you so, and you can re-enable it in your browser's site settings

The reminder sound can be turned on or off under Features. On Firefox the switch has no effect on the extension: notification sounds there are governed by your system notification settings.

Extension icon status

While a pomodoro is running, the extension icon shows the whole minutes remaining (43 minutes and 30 seconds left shows as 43). Below one minute it shows "<1", and while paused it shows "⏸". During a break it shows the minutes remaining as well, on a green background to tell the two apart.

Syncing across devices

TomatoTimer can sync your feature settings, language and theme preferences, and focus statistics through storage you own, so the web app, the extension, and every computer you use share the same data.

Under Settings → Storage, follow the four steps to enter your S3-compatible storage details (bucket, endpoint, access credentials) and apply the CORS rule on your provider. Once the test passes, turn syncing on. Your storage credentials never leave the device.

One thing to note: settings and statistics are synced, but a running timer is not — each device runs its own clock, independently of the others.

If you configure no storage, everything stays on the device and no feature is affected.

Settings

General

Language — Follow System / English / 简体中文 / 日本語
Theme — System / Light / Dark

Features

Pomodoro length — 45 minutes by default; any whole number from 10 to 120 is accepted, and out-of-range values snap to the nearest limit when you leave the field
Break length — 0 minutes by default, meaning no break; accepts 0 to 30
Pomodoros in a row — 1 by default, meaning the next pomodoro never starts on its own; accepts 1 to 12
Notification sound — on by default
Daily goal (Pro) — 0 by default, meaning no goal is set
Start/pause shortcut (browser extension only) — shows the current keys; click them to change the shortcut on your browser's shortcuts page
Export format (Pro) — CSV by default, with JSON as the alternative

Storage

See "Syncing across devices" above.

FAQ

The session ended but no notification appeared

In the web app, check that you allowed notifications for the site, and that a system focus or do-not-disturb mode is not suppressing them
In the extension, check that the extension is enabled

My statistics do not match on another device

Check that syncing is on for both devices and that both point at the same bucket
Data is pulled on a fixed schedule, so a pomodoro you just finished may take a moment to appear elsewhere

Nothing happens when I press the shortcut

Check that Start/pause shortcut under Features does not show "Not assigned". When the keys clash with another extension, your browser does not assign them to TomatoTimer; pick a different combination on your browser's shortcuts page
The shortcut only works while a browser window is in the foreground

With pomodoros in a row turned on, does the timer run forever?

No. It stops and returns to idle once the set number is done. To stop earlier, click Abandon during a pomodoro

Does the timer keep running once the panel is closed?

Yes. The countdown is driven by absolute timestamps, so closing the side panel or switching tabs makes no difference — the reading is still accurate when you come back
The extension reminds you on time even with the side panel closed. The web app needs its tab to stay open; close the tab and that reminder is missed