Blog / Build with AI /

Building a pomodoro timer extension with AI

The pomodoro technique is simple: work for 25 minutes, rest for 5, repeat, and take a longer break every fourth round. A timer is the whole tool. That makes it a very good first Chrome extension, because the idea is small but it touches the parts that trip beginners up: background work, storage and notifications.

Here’s how to get an AI assistant to build one, and what to watch for.

The finished thing

An extension with a toolbar popup that shows the time left, start/pause/reset buttons, a work/break mode label, and a desktop notification when a session ends. It keeps counting after you close the popup.

That last sentence is where the interesting problem lives.

Why the obvious version breaks

The first thing most people (and most assistants) write is a countdown inside the popup using setInterval. It works while the popup is open. Click elsewhere and the popup closes, its code stops, and your timer is gone.

Extensions run in separate parts: the popup (short-lived), and a background service worker (which also gets shut down when idle). For a timer, neither can be trusted to keep a ticking clock. If you want the background pieces explained, see content scripts vs background scripts in plain words and popup, options and side panel: extension screens explained.

The approach that works

Don’t count seconds. Store the end time and compare it with the current time.

  1. When the user presses Start, save endTime = now + 25 minutes in storage.
  2. Create an alarm that fires at that moment (Chrome’s alarms API is made for this and survives the service worker sleeping).
  3. When the popup opens, read endTime from storage and calculate the minutes and seconds left. Update the display once a second while it’s open.
  4. When the alarm fires, show a notification, switch the mode (work to break, or back) and store the new end time if the next session starts automatically.

The timer doesn’t “run” anywhere. It’s just a timestamp and a clock check, which is why it stays accurate.

Step 1: the manifest

Tell the assistant exactly what you need:

Write a Chrome extension using Manifest V3 for a pomodoro timer. Permissions: storage, alarms, notifications. A popup (popup.html, popup.js) and a background service worker (background.js). Don’t use setInterval for the real timer: store the end timestamp in chrome.storage.local and use chrome.alarms. Work is 25 minutes, short break 5, long break 15 after four work sessions. The popup shows the time left, the mode, and Start, Pause and Reset buttons. Explain every file briefly.

A correct manifest is short:

{
  "manifest_version": 3,
  "name": "Simple Pomodoro",
  "version": "1.0",
  "action": { "default_popup": "popup.html" },
  "background": { "service_worker": "background.js" },
  "permissions": ["storage", "alarms", "notifications"]
}

If the assistant asks for more permissions than that, ask why. Each extra permission is something users see and reviewers question. The Chrome extension manifest, explained line by line helps you read what you get.

Step 2: load it and test

You don’t need to publish anything to try it. Open the extensions page in Chrome, turn on developer mode, choose “Load unpacked” and select the folder. Click the icon and press Start.

Test in this order:

  1. Start a session, close the popup, reopen it. The time should still be right.
  2. Set the work length to one minute for testing, so you can see the alarm and notification quickly.
  3. Pause, close the popup, reopen. Does it stay paused with the correct time left?
  4. Close and reopen the browser. Think about what should happen and decide it deliberately.

When something fails, copy the exact error from the extension’s page or the popup’s inspector and give it to the assistant along with the relevant file. I covered the tools in debugging a Chrome extension: the tools that help.

Step 3: the small touches

Once the core works, these are cheap to add and make it feel finished:

  • A badge on the toolbar icon showing the minutes left, using chrome.action.setBadgeText.
  • Settings for the durations, saved in storage (see adding a settings page to your Chrome extension).
  • A “sessions completed today” count.
  • A quiet sound, but off by default, because sudden noise in an office or library is bad manners.

Resist the urge to add stats, themes and accounts. A pomodoro timer that does one thing well beats one with ten features.

What goes wrong

The alarm fires late or only once a minute. Chrome limits how frequently alarms can fire in some conditions. That’s fine for a 25-minute timer; it’s not fine for a second-by-second display. Only the popup shows seconds, and only while it’s open.

Notifications don’t appear. The operating system may be blocking them for the browser, or a focus mode may be on. Check system settings before debugging your code.

Messy state. Mode, end time, paused status and session count should live in one stored object. If the assistant scatters them across variables, ask for them to be gathered.

Resetting by accident. Put Reset where it can’t be hit by mistake, or ask for confirmation.

What it teaches

The timer is a good project because it forces you to learn that extension code isn’t always running, that state belongs in storage, and that time should be calculated, not counted. Those ideas carry over to reminders, trackers and almost any tool that waits for something.

If you’re keen on tab habits too, there is more on that in tab management extensions: why I care about tabs.

Key takeaways

  • Store an end time and compare, rather than counting seconds.
  • Use chrome.alarms for anything that must fire when the popup is closed.
  • Ask for the minimum permissions: storage, alarms, notifications.
  • Test with a one-minute timer first.
  • Keep it small; the value is in the single job done well.

What would you want your timer to do differently from the standard 25/5 rhythm? Start with that one change, and make it a setting.