# Pommedoro

**A Pomodoro timer that respects how your brain actually works.**

[Download the latest DMG](https://git.nixc.us/colin/pommedoro/raw/branch/main/releases/Pommedoro.dmg)

---

## The Problem with Traditional Pomodoro Timers

Every Pomodoro app does the same thing: a timer counts down, an alarm fires, and a dialog box demands your attention. You dismiss it. You always dismiss it. The break never happens.

This isn't a willpower failure. It's a design failure.

When you're deep in flow — writing, coding, designing — your mind is in a groove. A sudden alarm is a context switch, and human beings are wired to reject context switches. The instinctive response to an interruption during focus is to kill the interruption, not to obey it. So you click "dismiss" and keep working, and the entire purpose of the break is defeated.

Traditional timers treat breaks as binary events: you're working, then you're not. But that's not how attention works. Attention is a continuum. You can't jump from full focus to full rest without a bridge. **Transitions, not hard cuts, are the only way successful breaks will actually occur.**

## How Pommedoro Works

Pommedoro is built around the idea that your timer should *ease* you toward a break rather than ambush you with one.

### Phase 1: Escalating Awareness

During the last five minutes of a work session, Pommedoro begins painting soft teal gradients along the edges of all your screens. These are gentle — barely noticeable at first. They fade in and out slowly, like breathing.

As time goes on, the blinks become more frequent and more intense:

- **5:00 – 3:00 remaining**: A brief flash every 60 seconds. Subtle. A whisper.
- **3:00 – 1:00 remaining**: Every 30 seconds. You start to notice.
- **1:00 – 0:30 remaining**: Every 10 seconds. The edges are becoming familiar.
- **0:30 – 0:10 remaining**: Every 5 seconds. Your peripheral vision has accepted what's coming.
- **0:10 – 0:05 remaining**: Every 2 seconds. A steady pulse.
- **Last 5 seconds**: The edges hold solid. A countdown pill appears at the bottom of the screen.

The intensity of the gradient also escalates over this period — from a faint 15% opacity to a vivid 75%. Your subconscious has been processing this for five full minutes before the break screen ever appears.

### Phase 2: The Break Screen

When the timer reaches zero, the screen transitions to a full teal overlay. This isn't an alert dialog you reflexively dismiss — it *is* your screen now. It carries a simple suggestion:

> *"Stretch your neck and shoulders"*
> *"Step outside for a minute of fresh air"*
> *"Unclench your jaw and relax your shoulders"*

These are real, physical actions. Not platitudes. Not "take a break!" — that's meaningless. Pommedoro tells you *what to do* with your break, and if a suggestion doesn't resonate, you can dismiss it and it won't come back.

A 5-minute break countdown runs in the background. You can mark the suggestion as completed ("Success!"), skip it ("Next Time"), or permanently dismiss suggestions that don't suit you ("Don't Suggest").

### Phase 3: Reflection

After completing a suggestion, Pommedoro asks one question:

> *"How did that impact your readiness for the day?"*

Three options: **Feeling Great**, **About the Same**, **Not Really**. No journaling. No friction. Just a moment of honest self-assessment before you return to work.

### Phase 4: Ready When You Are

The final screen says "Ready when you are" and offers **Pause** or **Continue**. There's no urgency. The break timer is still visible but the message is clear: *you* decide when to go back. The next 25-minute cycle starts when you press Continue.

## Why This Works

The escalating gradient approach works because it operates on the same channel as your focus: your visual field. Rather than competing with your attention via an auditory alarm or a modal dialog, Pommedoro gradually *joins* your visual environment. By the time the break arrives, your brain has already been transitioning for five minutes. The break screen isn't an interruption — it's the natural conclusion of a process you've been subconsciously participating in.

This is the difference between someone tapping you on the shoulder while you're reading versus slowly turning up the lights in the room. One triggers a startle response and gets dismissed. The other lets your eyes adjust naturally.

The actionable suggestions matter too. "Take a break" is an instruction with no substance. "Do some pushups" or "Drink some water" gives your body and mind a concrete thing to switch to. The context switch succeeds because there's a real context to switch *into*.

## Features

- **25-minute work sessions** with 5-minute escalating visual transitions
- **Edge gradient warnings** that increase in frequency and intensity
- **Full-screen break overlay** with actionable wellness suggestions
- **5-minute break timer** with self-assessment reflection
- **Menu bar timer** with pause/resume support
- **Debug mode** for testing (1-minute cycles)
- **Launch at Login** via macOS LaunchAgent
- **Native macOS app** — no Electron, no web views, just AppKit

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history and recent changes.


## Install

### 1. Download

Go to [colinknapp.com/stories/pommedoro.html](https://colinknapp.com/stories/pommedoro.html) or download the DMG directly:

**[Pommedoro.dmg](https://git.nixc.us/colin/pommedoro/raw/branch/main/releases/Pommedoro.dmg)**

### 2. Install

In Finder, open your Downloads folder and double-click **Pommedoro.dmg**. When the disk image opens, drag **Pommedoro** into the **Applications** folder (or use the shortcut arrow if the window shows one). Then eject the disk image (right-click the "Pommedoro" volume in the Finder sidebar and choose Eject, or drag it to the Trash).

### 3. If macOS says "Pommedoro can't be opened" or "move to Trash"

Don't trash it. This happens because the app is distributed outside the Mac App Store.

1. Open **System Settings** → **Privacy & Security**.
2. Scroll down to the message about "Pommedoro was blocked…" (or "from an unidentified developer").
3. Click **Open Anyway** and confirm.

### 4. Open the app

Open **Applications** (or use Spotlight: **Cmd+Space**, type "Pommedoro") and double-click **Pommedoro**. It runs as a menu bar app — look for the timer icon in your menu bar.

## Build from Source

Requires macOS 13+ and Swift 5.9+.

```bash
make bundle
```

To install to `/Applications`:

```bash
make install
```

To build the DMG:

```bash
make dmg
```

To run directly:

```bash
make run
```

## Requirements

- macOS 13+
- Swift 5.9+
- Apple Silicon or Intel Mac

## Author

**Colin Knapp** — [colinknapp.com](https://colinknapp.com)

## License

This work is licensed under [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/).

You are free to share and adapt this work for any purpose, including commercially, as long as you give appropriate credit.
