thrown tomatos => throwntom
Pomodoro timer that won't let you forget to start timers, with repeating reminders until explicit confirmation.
throwntom is three programs that share one timer engine and one config:
throwntom— the original terminal UI. It runs the timer in-process and does not use the daemon yet (that move is planned; see the Daemon section).throwntomd— the background daemon: runs the timer, reminders and task store and serves a JSON API on a Unix socket. Every graphical client is a thin view over it.- Throwntom.app — the macOS window app, backed by
throwntomd.
Native Linux and Android clients are next. Once they exist the TUI is the odd one out — its own test surface for a timer the daemon already runs — so expect it to become a daemon client or be retired; it stays for now because some people simply prefer a terminal.
Prerequisites: Go (version in go.mod) for the TUI and daemon; the macOS app
additionally needs Xcode 26 with its command-line tools (swift build and the
SDK come from it — see macos/README.md).
Build or install the TUI:
go build -o throwntom ./cmd/throwntom
go install github.com/jwp23/throwntom/v3/cmd/throwntom@latestRun it:
throwntom
throwntom --config path/to/config.tomlBuild the daemon the same way (go build -o throwntomd ./cmd/throwntomd); on
macOS the app bundle carries its own copy, so you only need this to run the
daemon by hand.
The macOS client is one phase-coloured window with the tomato mascot on top: it
draws what throwntomd reports and sends the timer verbs back.
macos/install.sh # build, install to ~/Applications, and openThat takes about a minute. The first launch registers the bundled launchd agent
that runs throwntomd — the window shows "Starting timer…" for up to half a
minute while it comes up — and after that the app is in Spotlight and Launchpad,
and Launch at Login is a toggle in its application menu. Phase changes recolour
the window, and a reminder left outstanding posts a notification and bounces the
Dock icon; press ⌘/ in the window for every shortcut.
Quitting the app does not stop the timer: the daemon keeps running (and keeps
reminding you) under launchd. That is deliberate — see
docs/adr/006-daemon-lifecycle-and-config-reload.md. Two controls in the window
(and in the Timer menu) end it, and they mean different things: Done for
Today ends the work day, so nothing reminds you again until tomorrow, and
Stop Timer Service boots the launchd agent out, so the daemon exits and
nothing is timing at all. A single phase is stopped without ending the day from
a terminal with tools/tomctl cmd stop.
The equivalent of Stop Timer Service by hand — note that an app which has not been told to stop re-registers the agent after a few failed connections, so quit it first:
launchctl bootout gui/$(id -u)/com.jwp23.throwntom.daemonThe app registers it again the next time it opens. Rebuilding is the same
macos/install.sh; details and the daemon-only dev loop are in
macos/README.md, and driving the daemon or checking the window from a
terminal is in docs/development.md.
The window reports a failure as a plain sentence and never as an error's own text. When that sentence is not enough, what actually went wrong is in the system log:
/usr/bin/log show --last 1h --predicate 'subsystem == "com.jwp23.throwntom"' --style compactThe categories and what is recorded are in docs/development.md.
The TUI reads these at its prompt; the daemon accepts the same lines through
tools/tomctl cmd <line>, except that start and confirm prompt for task
focus and so fail non-interactively — use the daemon's /v1/timer/start and
/v1/timer/confirm routes for those (see docs/development.md). The macOS
window exposes the timer verbs as buttons and menu items and the task commands
through its tasks panel.
start- start work period, or take the phase you are owed (at the end of a phase it does whatconfirmdoes)new-cycle- start a fresh cycle now (reset cycle progress, keep today's total; a finished phase is still counted)lunch- take the lunch break (lunch_minutes, default 60); it starts from any state and the pomodoro after it begins a fresh blockmeeting <duration>- attend a meeting of the length you name (example:meeting 30); it starts from any state and the time spent in it is credited as pomodorospause- pause the active pomodoro or break timerresume- resume a paused pomodoro or break timerskip- end the running phase now and move to the next stage (the skipped phase is not counted)stop- suspend the cycle and return to idle, keeping the owed phase and focused tasksconfirm- acknowledge transition and start next phase nowsnooze <duration>- keep the owed phase and focused tasks, ask again later (example:snooze 10m)unsnooze- end a snooze now and bring the reminder straight backskip-today- stop reminders for the current daystats- show productivity dashboard (today, week, month, all-time, streaks, patterns)status- print current statustest-sound- play a test tone immediately to verify terminal audio/bellquit- exit throwntomexit- alias forquit
snooze works whenever a reminder is ringing, not just in the morning — including
while waiting for confirm at the end of a pomodoro or break. It doesn't lose
anything: it just asks again later.
unsnooze undoes it. A snooze only silences the reminder — the reminder itself is
still outstanding and unanswered — so ending the snooze early brings it back at
once, exactly as running out the clock would have. That is what separates it from
start and skip-today, which also clear a snooze but retire the reminder with it.
lunch is the one break you choose rather than earn: no schedule starts it and
no finished pomodoro leads to it, so it is available from any state and never
offered by the timer itself. Taking it ends the current block — the count
toward the long break starts again, while the day's total stands — so the
pomodoro you come back to is the first of a fresh block.
meeting is chosen rather than earned too, but it is not a break: it is worked
time you spend away from the timer. When it ends, its length is credited as
pomodoros — rounded to the nearest, with half rounding up, so a 60-minute meeting
is worth 2 at the default 25-minute pomodoro and a 10-minute one is worth none.
Those credits count toward the day's total and toward the long break alike, so a
meeting earns the break the same work done at the timer would have: the longest
one its credits allow. A meeting that completes the block you were part-way
through — or spans a block boundary outright — is followed by the long break;
one that lands mid-block is followed by the short one. skip ends a meeting early and still
credits the time actually spent in it, which is what separates ending a meeting
from skipping a pomodoro.
stop is a suspend, not an abandon — for stepping away without ending
the day. It returns the timer to idle but keeps the phase you were owed, your
progress toward the long break, and your focused tasks, so start picks the cycle
back up: stop after finishing a pomodoro and the next start gives you the break
you earned. To drop the owed phase instead, use new-cycle for a fresh cycle or
skip-today to end the day.
Manage focused tasks for your pomodoro sessions. Tasks are persisted to ~/.config/throwntom/tasks.json.
task add <desc>- add a new tasktask done <n>- mark task numbernas completedtask remove <n>- delete task numberntask list- show active taskstask completed- show completed taskstask clear- clear completed taskstask focus <n>- focus on taskn, in any timer statetask unfocus <n>- remove focus from task at positionntask up <n>- move focused task up in prioritytask down <n>- move focused task down in priority
Focus is not tied to a running pomodoro: you can focus and unfocus in any timer state, including while idle, so a session can begin with the work already named. Starting a pomodoro always asks which tasks it is for, offering back whatever is already focused; confirming into a work phase asks only when nothing is focused yet.
throwntom automatically saves session state to ~/.config/throwntom/session.json after every command and on shutdown. When you restart, it restores:
- Timer position (adjusted for wall-clock time elapsed while closed)
- Engine state (work, break, paused, awaiting confirmation)
- Completed pomodoro counts for the day
- Focused task selections
If the saved session is from a different work day (see day_start), it is discarded and throwntom starts fresh. If the timer expired while closed, it transitions to awaiting confirmation. Paused timers remain paused with their remaining duration preserved.
A pomodoro is wall-clock time, so a running phase keeps counting while nothing
is running: the session stores when the phase began, not how much of it was
left. Restarting the daemon ten minutes into a 25-minute pomodoro leaves 15
minutes, not 25, and a phase that ran out while the daemon was down comes back
already complete and awaiting confirmation. Time spent is what carries across
the outage; the duration it is measured against always comes from your current
config, so an edit made during the outage still applies. This is deliberate —
see
ADR-008.
Stopping the
timer service is therefore not a way to pause: use pause, which stores the
remaining duration instead.
throwntom records every meaningful event (pomodoro start/complete, breaks, pauses, snoozes) to ~/.config/throwntom/events.jsonl. This append-only log powers the stats command, which displays:
- Today / This Week / This Month / All Time — pomodoro counts, focus time, pauses, snoozes
- Streaks — current and longest consecutive days with at least one pomodoro
- Patterns — best day of the week, most productive hour, snooze/pause rates
Pomodoro counts carry a tier glyph and color (thresholds configurable):
| Tier | Default range | Glyph | Color |
|---|---|---|---|
| Cool | 0–2 | ○ | gray |
| Warm | 3–5 | ◐ | tomato |
| Hot | 6+ | ● | teal |
throwntomd runs the timer, reminders and task store as a background
process and serves a JSON API over ~/.config/throwntom/daemon.sock
(see docs/designs/native-macos-client.md for the routes). It plays no
sound of its own — reminders are heard through whichever client is running.
Only one instance runs at a time (daemon.lock). The TUI does not talk to the
daemon yet — it runs its own copy of the engine — so do not run both at the same
time: they share session.json.
Control the daemon from the command line with tools/tomctl (see
tools/tomctl/README.md for usage and build instructions, and
docs/development.md for driving phases and stopping the daemon). The state
document's paused_from field names the phase a pause interrupted, so a
client can keep showing that phase while paused.
Config file location: ~/.config/throwntom/config.toml
The first time throwntomd starts without one, it writes a fully documented
config.toml there: every setting, with its default, commented out. Edit the
file in place — uncomment a line and change it. An existing config is never
overwritten. The macOS app opens this file with Open Config File… (⌘,).
Example config.toml:
# Settings outside a section must stay above [pomodoro]: TOML puts a bare key
# written after a section header inside that section.
day_start = "04:00"
repeat_secs = 20
repeat_limit_secs = 300
sound_command = ["paplay", "/usr/share/sounds/freedesktop/stereo/bell.oga"]
morning_reminder_pending = true
emoji = true
float_window_when_waiting = false
paused_too_long_minutes = 10
bounce_dock_when_paused = true
[pomodoro]
work_minutes = 25
short_break_minutes = 5
long_break_minutes = 15
lunch_minutes = 60
long_break_every = 4
# days omitted → defaults to weekday (Mon-Fri)
[[schedule]]
time = "09:15"
# specific-day override carves out from the default group
[[schedule]]
days = ["Fri"]
time = "10:00"
[stats]
tier_low = 2
tier_mid = 5repeat_limit_secs bounds how long an unanswered reminder keeps alerting, so a
reminder nobody is around to acknowledge stops on its own rather than ringing
until you quit. Like sound_command it describes the terminal UI: throwntomd
plays nothing to repeat, and on macOS the app chimes on each published ring,
the first included, until the reminder is answered.
The work day runs from day_start to the same time the next morning, not from
midnight to midnight. Default 04:00, written as 24-hour HH:MM.
It matters for a shift that runs into the small hours. The day's pomodoro count
and the progress toward the long break carry across midnight rather than
resetting mid-shift, and Done for Today said at 2am clears at the next
day_start — while you sleep — instead of standing until the following
midnight. A day worked between these hours never meets the boundary at all.
The boundary is a wall-clock time. A day that a daylight-saving change makes 23 or 25 hours long is still one work day; nothing here adjusts for the offset.
Off by default. When on, the macOS window is kept above other applications' windows while a reminder is waiting to be answered, and drops back to the ordinary level as soon as the reminder is confirmed or snoozed. It is for a cluttered screen, where a reminder is easy to lose behind whatever else is open.
It never takes keyboard focus. Raising a window's level changes the stacking order only; taking the keyboard is a separate act the app does not perform, so the window cannot interrupt what you are typing — it can only appear in front of it. The daemon raises no window of its own: it reloads this setting and publishes it in its state for the macOS app to read. The terminal UI has no window to raise.
Ten minutes by default. A pause is easy to walk away from and hard to notice
you are still in, so once one has lasted this long the daemon publishes it as
paused_too_long and the macOS app bounces its Dock icon. Resuming before the
threshold passes does nothing at all.
The daemon keeps the clock and nothing else: what to do about a forgotten
pause is the client's, the way every other reminder is
(docs/adr/003-clients-own-user-facing-notification.md). The pause keeps its
age across a daemon restart, so restarting is not a way to get the ten minutes
back. The terminal UI does not use this setting.
On by default. Turns off the Dock bounce paused_too_long above drives on
macOS, for anyone who finds it more distracting than useful. It changes
nothing about paused_too_long_minutes: the daemon keeps the same clock and
publishes paused_too_long on the same schedule regardless, since the clock
and the threshold are not this setting's to change — only whether the app
acts on the answer is (ADR-003). The daemon raises no Dock icon of its own:
it reloads this setting and publishes it in its state for the macOS app to
read. A live edit that turns it off also calls off a bounce already in
progress; the terminal UI does not use this setting.
sound_command applies to the terminal UI only. throwntomd plays no sound
at all: it publishes state and each client presents it on its own platform,
so on macOS the reminder is the app's banner plus a chime the app plays itself
on every ring — the banner carries no sound (see
docs/adr/007-the-daemon-plays-no-sound.md,
docs/adr/009-the-chime-is-the-only-audio-path.md).
sound_command is an optional TOML string array: the first item is the
executable, the rest are its arguments. Setting it changes how the terminal UI
makes noise:
- On macOS, it replaces the built-in sound entirely — throwntom runs
your command instead of
afplay, for every sound (morning nudge, confirm reminder,test-sound) with no way to tell them apart by ear. - On Linux, it is tried first and, if it fails, throwntom falls back to
paplay,canberra-gtk-play,aplay, then the terminal bell.
On macOS, to pick a different system sound (the built-in choice is Blow for
the morning nudge, Glass for confirm reminders, Tink for test-sound):
sound_command = ["afplay", "/System/Library/Sounds/Purr.aiff"]To silence sound entirely (e.g. while testing or in a meeting), set:
sound_command = ["true"]/usr/bin/true exits 0 immediately and prints nothing, so throwntom reports
success with no audio.
throwntomd watches config.toml and applies edits within a few seconds,
with no restart. It polls every two seconds and waits for an edit to stop
changing before applying it, so a save lands on the second poll that sees it. The pomodoro already running is re-derived from the
new durations: it keeps the time it has spent and runs for whatever the new
duration leaves. Shortening a duration below the time the current phase has
already spent ends that phase immediately — the edit says the phase should
already be over. A file that does not parse is reported on the daemon's
stderr and ignored; the config in force stays in force.
Reloading covers [pomodoro], [[schedule]], day_start, repeat_secs,
repeat_limit_secs, float_window_when_waiting,
paused_too_long_minutes and bounce_dock_when_paused. The rest needs a restart
of whichever process reads it:
sound_command—throwntomdplays no sound at all (see above), and the terminal UI that does use it builds its notifier once, at startup; neither rereads it.morning_reminder_pending— it answers whether today's morning reminder is owed when the daemon starts, a question already settled by the time an edit arrives.emojiand the[stats]tiers — client settings, read bythrowntomwhen it launches.
An edit made while the daemon is stopped lands the same way. The phase that
was in flight keeps the time it had already spent — that keeps accruing
through the outage, see A phase counts through
downtime — but it is measured against the
duration in your config now. Changing work_minutes from 25 to 50 with the
daemon stopped and restarting ten minutes in leaves forty minutes, exactly as
it would have with the daemon running.
If you only need to silence one running reminder rather than sound in
general (for example, ducking out of a meeting), don't edit the config —
run tools/tomctl cmd snooze 10m or tools/tomctl cmd stop against the
running daemon instead.
Schedule supports day aliases: "weekday" expands to Mon-Fri, "weekend" to Sat-Sun. Specific-day entries automatically carve out from alias expansions.
cmd/throwntom/— main binary: CLI entry point, Bubble Tea model, renderingcmd/throwntomd/— daemon binary: background process serving the JSON APIinternal/analytics/— productivity dashboard computationinternal/config/— TOML config parsinginternal/core/— timer/task/reminder orchestration shared by the TUI and daemoninternal/daemon/— daemon HTTP API, socket lifecycle and shutdowninternal/engine/— pomodoro state machineinternal/eventlog/— append-only event loginternal/notifier/— desktop notifications and soundinternal/pomodoro/— the pomodoro timer: the engine with a wall clock on itinternal/reminder/— reminder schedulinginternal/scheduler/— work schedule (days/times)internal/session/— session persistenceinternal/task/— task storetools/tomctl/— command-line client for the daemon APItools/icon-colors.sh— dominant colours of the app icon as hex (ImageMagick); keepsDESIGN.md'sicon-*tokens traceabletools/unmatte-white-background.swift— recovers the alpha channel of art exported over white; regeneratesdocs/images/throwntom.pngfromdocs/images/throwntom-source.png(seedocs/development.md)tools/sonar-audit.sh— reports SonarCloud issues/hotspots on a branch; CI runs it on main to flag drifttools/swiftmutantsgate/— fails on any unexcluded Survived, Crash, Timeout or NoCoverage mutant in swift-mutation-testing JSON reports and counts Unviable ones;-summarywrites the per-file table the weekly Swift mutation workflow files as its tracking issuetools/swiftmutantshard/— splits a Swift target's files into line-count-balanced shards and prints the--excludepatterns for one shard; the weekly Swift mutation workflow runs ThrowntomUI across its shards;-scope sonar-project.propertiesalso excludes the pass-through files insonar.coverage.exclusions(ADR-018)tools/dev-quiet.sh— runs throwntom against an isolated, silent config for manual testing (see Dev tools)tools/mascot-snap.sh— renders every mascot pose offscreen to PNGs (seedocs/development.md)tools/app-capture.sh— screenshots the app window by window number, no Accessibility permission neededtools/lsreg/— lists and prunes Launch Services registrations left behind by worktree builds (seetools/lsreg/README.md)macos/Throwntom/— Swift package: the macOS window app and daemon clientmacos/build.sh— buildsThrowntom.appwiththrowntomdembedded (seemacos/README.md)macos/install.sh— the dev loop: quit, stop the agent, build, install to~/Applications, openmacos/mutation-control.sh— negative control for Swift mutation testing: a planted survivor must be reported Survived before any score is trusted (ADR-015)macos/mutate-file.sh— runs swift-mutation-testing and the survivor gate over the files matching a keep-regex, for local triage of one file at a timedocs/development.md— driving the daemon and checking the app from a terminale2e/— end-to-end tests (build tag:e2e)integration/— integration tests (build tag:integration)
go test -timeout 30s ./... -v
go vet ./...
go build ./cmd/throwntom ./cmd/throwntomd # TUI and daemon
cd macos/Throwntom && swift test # macOS app (needs Xcode)Install local git hooks:
./scripts/install-git-hooks.shCommit-time checks in .githooks/pre-commit run:
gofmtverification (gofmt -l .)- Airbnb Swift style when Swift files are staged (
macos/swift-lint.sh;--fixto autocorrect) - fast tests (
go test -timeout 30s ./...)
Heavier checks intentionally kept out of pre-commit and run in CI:
- lint + complexity gate (
golangci-lint run ./...) - integration tests (
go test -timeout 30s -tags=integration ./integration) - e2e tests (
go test -timeout 30s -tags=e2e ./e2e) - security scan (
govulncheck)
tools/dev-quiet.sh [throwntom args...]Runs throwntom with HOME pointed at a throwaway directory (cleaned up on
exit) and a config.toml there setting sound_command = ["true"]. It
neither plays sound nor reads or writes your real ~/.config/throwntom, so
it's safe to use while working or in a meeting without disturbing a real
session. Extra arguments (e.g. --config) are forwarded to throwntom.
- The daemon plays no sound; the notes below describe the terminal UI.
- On macOS, notifier uses
afplaywith a system sound chosen by name (morning→Blow,default→Glass,test→Tink), unlesssound_commandis set, in which case that command replacesafplayfor all of them. - On Linux, notifier first tries
sound_command(if configured), thenpaplay,canberra-gtk-play,aplay, and finally terminal bell (\a). sound_commandis optional and must be a TOML string array where the first item is the executable, and remaining items are args. See Config for the silent-testing recipe.