Breaks

KO | EN

gitlite — search

#python #hacktoberfest #react #llm #deep-learning #nodejs #windows #awesome #cli #kubernetes #pytorch #security #ios #mcp

(★ 27)

A small, quiet Pomodoro timer that lives in your Mac menu bar. SwiftUI, sandboxed, focus journal, streaks, global hotkeys.

Breaks Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Breaks

A small Pomodoro app that lives in your Mac menu bar.

I built Breaks because every other timer either nagged me too much, hid in a Dock icon I never wanted, or treated breaks as an afterthought. This one is the opposite. It's quiet, it remembers what you were focused on, and it actually cares whether the break was any good.

![Platform](https://img.shields.io/badge/platform-macOS%2013%2B-blue)
![Swift](https://img.shields.io/badge/Swift-5.0-orange)
![SwiftUI](https://img.shields.io/badge/UI-SwiftUI-purple)

## What it does

- Lives in the menu bar. Click the icon, get a popover. No Dock clutter, no extra window.
- Pomodoro the way you want it. Tweak work / short break / long break lengths, sessions per cycle, sounds, auto-start behavior.
- Global hotkeys for start/pause, skip, and reset cycle. Bind whatever keys you like. Works even when the app isn't focused, because it uses Carbon's `RegisterEventHotKey` instead of the flaky `NSEvent` route.
- A focus journal that's actually useful. Pick a focus for the day, label each block, mark it good, messy, or skipped. It's quick, takes one tap during the break, and adds up over the week.
- **Breaks AI**, on-device. A weekly summary and a chat ("when did I focus best?", "which project took the most time?") backed by Apple Foundation Models. No servers, no telemetry, no API keys. Requires macOS 26 with Apple Intelligence enabled.
- Per-project stats. Tap any project in the weekly review to see week / month / all-time minutes, a 7-day chart, and outcome breakdown.
- Cycle templates. Six built-in presets — Pomodoro, 52/17, Deep Work, Flowtime (90/20), Ultradian, Quick — and you can still tune the durations yourself.
- Markdown export. Dump your full focus journal to a `.md` file you choose. Daily blocks, outcomes, projects, totals.
- Custom break suggestions. Edit the short/long break ideas, add your own, and cycle through them from the timer.
- Calendar export. Optional EventKit export writes completed focus blocks to your chosen calendar.
- Streaks with grace. Miss a day and you get a small per-week pause budget before the streak decays. Life happens.
- Idle detection. If you walked away mid-session, Breaks notices and asks whether the time should still count.
- Survives sleep. Close the lid, come back, the timer is still where it should be. It's driven by an `endDate` plus `NSWorkspace` sleep/wake notifications, so it doesn't drift.
- Sandboxed and small. No analytics, no account, nothing leaves your machine. State lives in `UserDefaults`.

## Install

**Option A — Mac App Store**

[![Download on the Mac App Store](https://tools.applemediaservices.com/api/badges/download-on-the-mac-app-store/black/en-us?size=250x83)](https://apps.apple.com/xk/app/breaks-pomodoro-timer/id6766944942?mt=12)

**Option B — Direct download**

Grab the latest DMG from [Releases](https://github.com/GjinPrelvukaj/Breaks/releases/latest):

1. Download `Breaks.dmg`
2. Open the DMG and drag `Breaks.app` into `/Applications`
3. Launch from `/Applications` — no right-click needed, the build is notarized

Requires macOS 13.0 or later. Universal binary (Apple Silicon + Intel).

## Build from source

```sh
git clone git@gjinprelvukaj.github.com:GjinPrelvukaj/Breaks.git
cd Breaks
open Breaks.xcodeproj
```

Then Cmd+R in Xcode. Or from the CLI:

```sh
xcodebuild -project Breaks.xcodeproj -scheme Breaks -configuration Debug build
```

Requires a recent Xcode.

## Reset state

Everything is in `UserDefaults` under the bundle ID. To wipe settings, history, and the journal in one go:

```sh
defaults delete com.gjinprelvukaj.Breaks
```

## How it's built

SwiftUI all the way down. The codebase is split into four small folders:

```
Breaks/
├── BreaksApp.swift              entry point + menu bar label
├── SharedStorage.swift          UserDefaults keys, widget snapshot
├── Models/
│   ├── BreakTimer.swift         the controller. modes, ticks, idle, sleep
│   ├── BreakSuggestionLibrary.swift  editable break suggestions
│   ├── TimerSettings.swift      every user-tunable knob
│   ├── SessionHistory.swift     daily counts and streak math (with pause budget)
│   └── FocusJournal.swift       today's focus, per-block labels, weekly rollups
├── Views/
│   ├── TimerPopover.swift       routes between onboarding, stats, settings, timer
│   ├── TimerContentView.swift   main page. check-in, dashboard, panels
│   ├── TimerRing.swift          the circular progress ring
│   ├── OnboardingView.swift     three-step onboarding
│   ├── StatsView.swift          streak hero, heatmap, weekly review
│   ├── SettingsPanel.swift      collapsible settings sections
│   └── ReusableComponents.swift segmented pickers, hotkey rows, etc
├── Style/                       button styles, hex colors, glass cards
└── System/
    ├── CalendarExporter.swift   optional completed-session calendar export
    ├── Hotkeys.swift            Carbon global hotkeys
    ├── LoginItemController.swift SMAppService wrapper
    └── NotificationPermissions.swift
```

A few things worth flagging if you go editing:

- **Tick decoupling.** `BreakTimer.remaining` only updates at action boundaries (start, pause, reset, fire). Per-second updates flow through a separate `TickClock` `ObservableObject`. That keeps the popover view tree from re-rendering every single second. If you add UI that needs the live countdown, observe `TickClock`, not `BreakTimer`.
- **Persistence per-property.** Each `@Published` setting writes itself in its own `didSet`. There's no central save call. New settings should follow the same pattern.
- **Pruning at write time.** `SessionHistory` is capped at 120 days and `FocusJournal` logs at 30, pruned when you write rather than when you read. That keeps cold-start reads cheap.
- **Streak math.** `SessionHistory.streakSnapshot(pauseDayBudget:)` walks day-by-day from the earliest record forward and decays by 1 per missed day, except the first N missed days each ISO week are absorbed by the budget. That's the only non-trivial bit of logic in the app.
- **Explicit imports.** The project sets `SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY = YES`, so every file has to import what it actually uses (`import Combine` for `@Published`, etc). Don't rely on transitive imports through `SwiftUI`.

## Permissions

Breaks asks for three things:

- Notifications, so you actually know when a session ends. Granted from the onboarding screen.
- Launch at login, optional, via `SMAppService`. Toggle it in settings.
- Calendar access, optional, only if you enable completed-session export.

That's it. No accessibility, no automation, no network.

## Roadmap

What's planned, what's shipped, what might happen one day: [Breaks Roadmap](https://github.com/users/GjinPrelvukaj/projects/1).

Recent shipped highlights:
- **v1.4.1** — first notarized DMG release, approved and live on the Mac App Store.
- **v1.4** — amber default accent, bigger timer ring, stats empty states, curated icon picker for break suggestions, quiet popover (no banners while you're already looking at the timer), Liquid Glass popover background.
- **v1.3** — Breaks AI weekly review and chat (on-device via Apple Foundation Models), per-project stats, six cycle presets, Markdown export.
- **v1.1** — editable break suggestions, optional Calendar export, in-app website link.

If something on there matters to you, react on the issue with a 👍, that's how I prioritize.

## Status

I use it daily. It probably has rough edges if your workflow is very different from mine. PRs and issues are welcome, but fair warning, this is a personal app first.

## License

MIT. Do whatever you want with it.

Breaks

Breaks Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Breaks

Breaks Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README