Everything FocusTimer can do, and where to find it.

Getting started

FocusTimer lives in two places, and they're the same surface:

• The menu bar ring — a small ring that counts down the current phase all day. Click it for the full timer in a popover. It flashes gently when a paused timer is forgotten.
• The main window — the same timer, bigger, plus toolbar doors to Stats and History.

The Settings window

Open Settings with ⌘ , or from the menulet's ⋯ menu. It works like System Settings: a searchable sidebar of eleven panes listed alphabetically, and a grouped form on the right. It opens on General, centered, every time.

In the pane pictures throughout this guide, switches are shown at their factory defaults unless the caption says otherwise. Grey text beneath a group is the app's own explanation — the same words you'll read in the app.

The timer surface

Top to bottom, every element of the home screen:

• The doors (top icon row) — tag, timer sets, strict padlock, and activities. They open the picker pages; the padlock arms strict mode in place. Once a session is running or paused the doors fade out — the session is committed.
• The ring — fills up with elapsed time, classic pomodoro style. Purple during focus, blue during breaks; in the final 10 seconds of a phase it shifts to an urgent warm gradient. The phase names itself inside the ring — "Focus", "Strict Focus", "Short Break", "Long Break".
• Transport — see Running a session.
• The intent field — "What are you focusing on today?" Type a goal and press Return. While the session runs it becomes a ticker ("Currently focusing on: …"); double-click it to edit mid-session; the ⓧ outside the field clears a committed goal.
• The orange status line — one slot, two readings that trade places: Round 2/4 · Next up 5m short break while you work, Today · 4 focus sessions completed · 1h 40 min between runs. If the selected activity has a schedule, a red budget warning can take this slot.
• Current Session footer — display-only context for the running record: the activity line, then set and tag, each in its own color. Word-form empties ("No Activity", "No Tag") — a slot is never blank.

The menu bar ring — Settings › Menu Bar

Running a session

• Play / Pause / Resume — the big button; also ⌘ ↩. Pauses are recorded (count and total paused time land in the session record).
• Reset (⌘ R) — abandons the current phase and returns it to full duration. For a begun focus session this is a void — the record keeps the time, credit is not given.
• Skip (⇧ ⌘ K) — jumps to the next phase. A skipped focus session is voided; a skipped break is just noted as cut short. Skips never advance the round and never trigger auto-start.
• End (red stop) — ends the whole run: session voided if one is open, the cycle returns to Round 1. Appears only while a session is active, and always asks first — the confirmation replaces the transport row and is phase-honest about what ending means.
• Switching sets mid-run — not allowed; the set is a commitment for the run. Tags stay changeable.

Auto-start

Two independent switches in Settings › Timer (both off by default): Auto-start breaks and Auto-start focus sessions. Only natural completions auto-start the next phase — a skip never does. The pane is pictured under How counting works.

How counting works

The rule the whole app is built on (read it in the app under Settings › About › How FocusTimer Counts…):

• Breaks are timing data, never scored — History shows them as "Taken" or "Cut Short", neutrally.
• Rounds — only completed focus sessions advance the round; every Nth earns the long break (N is the set's "rounds before long break").
• Goals & streaks — a day meets its goal by completed focus sessions; a streak is ≥ 1 completed focus session per logical day.
• Day start — sessions before your day-start hour count toward the previous day, for night owls.

Settings › Timer

Timer sets

Every timing scheme is a set: focus / short break / long break / rounds before long break. Switch, create, and edit sets from the timer's tray door — not from Settings. Applying a set writes the four values — a running session is never interrupted.

Built-ins are immutable in name and timing, but you can give any of them your own icon and color. Custom sets are fully yours:

• Name (up to 17 characters), icon, and color — the set's identity shows in the picker, the footer, and History.
• The four timings — focus and breaks 1–180 minutes, rounds before long break 2–8.
• Strict by default — whether selecting this set arms the padlock.
• Prevention — whether sessions on this set block apps and/or websites, and what happens on breaks (see Distraction prevention).
• Custom sets Syncs and survive Restore Defaults — they're your content, like tags.

Strict mode

The padlock door arms strict for the next focus session. While a strict focus session runs:

• Pause and Skip are removed — not disabled, gone. The transport collapses to Reset · End.
• The ratchet — you can arm strict anytime (it engages a running focus immediately), but you cannot disarm it mid-focus. Reset or End Run are the only exits, and both are voids.
• Breaks are never locked, and the phase title reads "Strict Focus" whenever strict is armed, so there's never a surprise.
• Arming is a per-sitting choice — it isn't remembered across launches; the active set's default seeds it.

Tags

A tag is the kind of work — Writing, Code, Admin. One tag is active at a time; it sticks across sessions and launches until you change it. Tags live behind the timer's tag door, not in Settings.

• Create from the tag door: type a name (up to 17 characters), pick a palette color. Names are unique, case-insensitive.
• Tags vs. Archived — two subpages. Archiving hides a tag from pickers without touching history; reusing an archived name revives the same tag.
• Delete is permanent and fresh-start: history keeps its sessions' snapshots, but recreating the same name later makes a new tag identity.
• Retroactive tagging — right-click any History row to change its tags after the fact.
• Filter History and Reports by tag; the Stats lens breaks focus time down by tag.

Activities

An activity is the project — the biggest unit of context. Selecting one configures the timer in one click; its pages live behind the checklist door.

• Info — name, icon, color, description, and status (Active ⇄ Archived).
• Defaults — an activity can carry its own timer set, tag, and strict preference. Selecting the activity applies them (never interrupting a run — deferred changes are applied honestly and logged).
• Schedule — start/end dates, time allowance, and work-week days; the timer's status slot turns into a budget line and warns in red in the last quarter.
• Billing — hourly rate and currency. Sessions snapshot the rate at the time they run, which is what Reports turns into money.
• Archive vs. Delete — archive to shelve a project; delete is permanent (a 30-day tombstone protects against restore resurrection). Session history always keeps its snapshots.

Distraction prevention

Two lists live in Settings › Prevention; whether they're enforced is decided per timer set in the set editor.

• The first session that blocks a browser triggers a one-time macOS permission prompt to control that browser.
• Each set also chooses its break behavior — whether breaks keep the block or lift it.
• Ending the session always ends the blocking, instantly.

Sounds & ambience

The picture shows the pane; the tables below give every default and whether it syncs.

Alert sounds

Every enabled event gets its own picker drawn from the system sound library, so you can swap any of those defaults.

Ambience — generated background noise

The envelope is part of the design: a quiet hold after the start chime, a ~15-second rise, and a gentle wind-down across the final 15 seconds so the phase lands at silence. Pausing or muting fades out quickly.

Notifications & Do Not Disturb

Stats

Open from the main window's chart button. Everything is derived at query time from raw session records, honoring your day-start hour.

• Today's tally — the goal ring (completed focus sessions vs. your daily goal).
• Streaks — current and best; a day counts with ≥ 1 completed focus session, and an empty today doesn't break the streak until the day actually ends.
• Trend chart — focused time by Week / Month / Year (the one orange control on the screen).
• Calendar heat map — a year of days; full purple = goal met.
• Focus by time of day — the weekday × hour heat map that shows when you actually focus.
• Lenses — switch the screen between overall focus and per-activity / per-tag breakdowns.

Settings › Stats

History

The complete ledger, grouped by day, newest first. Each row: phase (in identity color, "Strict Focus" marked by the lock), set, tag, duration — partials read "11:38 of 50:00" — and the honest outcome badge: Completed, Voided · Skipped / Reset / Interrupted, breaks as Taken / Cut Short.

• Filter — the slider button opens a popover with Event, Result, Tag, Set, and When; active filters show as chips with an honest match count.
• Detail — click a row for the full record, pauses included.
• Retroactive tags — right-click a row to adjust its tags.
• Delete Session… — right-click; the confirmation states the stats/streak consequence. Deletion is a tombstone, so restoring an old backup can't resurrect it.

History has no Settings pane — everything about it is on the screen itself.

Reports

Activity Reports turn the ledger into answers — for invoices, standups, or your own accounting.

• Period — Today, and wider windows via the period dropdown; filters use the same grammar as History.
• Tiles — totals for the filtered slice, including money.
• Time by Activity — a breakdown with Unassigned always last; clicking a row drills the whole report into that activity.
• Focus Over Time — the filtered trend.
• Summary ⇄ Sessions — flip between the aggregate and the underlying session list.
• Money — computed only from each session's snapshotted rate, kept per-currency, never converted. Rate changes are lifecycle facts — old sessions keep old rates.
• Export — the report as CSV, ready for a spreadsheet.

Export

One-click export of every recorded session — from the Stats toolbar or Settings › Export. Nothing is uploaded anywhere; the file goes only where you choose.

Backup & restore

Backups are complete, human-readable JSON copies of your history (sessions, tags, activity events, custom sets), written automatically and verified.

• Restore is unavailable while the timer is running — stop the timer first.
• Safety copies — written automatically before restores and schema migrations, and when a damaged file is set aside. They get their own section in the pane when any exist.
• If the store is ever damaged — the app tells you loudly at launch and walks you through restoring from the dated list. Corruption is never silent.

iCloud

Everything iCloud is opt-in and lives in one pane. Nothing touches iCloud until you turn it on.

If you're not signed in to iCloud, the pane says so at the top and the switches are disabled until you sign in from System Settings.

General, shortcuts & automation

The General pane is pictured in The Settings window above. What's in it:

Keyboard shortcuts

Shortcuts app

FocusTimer ships App Intents: Start Timer, Pause Timer, Skip Phase, End Run, and Sessions Today (a query). Use them from Shortcuts, Spotlight, or automations — for example, a personal automation that switches your Mac's Focus mode whenever a session starts. The built-in Do Not Disturb toggle uses the same machinery.

Settings quick reference

Eleven panes, alphabetical — what lives where:

Note what has no Settings pane, by design: timer sets, tags, and activities are all managed on the timer surface itself, and History and Reports are configured on their own screens.