TomatoBar: a sandboxed Pomodoro timer for the macOS menu bar

What TomatoBar actually is, and who it is for

TomatoBar is a Pomodoro timer that lives in the macOS menu bar. The README describes it as "world's neatest Pomodoro timer for the macOS menu bar" and lists the feature set plainly: configurable work and rest intervals, optional sounds, discreet actionable notifications, and a global hotkey. That is the whole product. There is no task list, no project tagging, no weekly report.

The audience is narrow on purpose. If you already work the Pomodoro technique and want the timer a click away rather than in a browser tab or a phone on the desk, this fits. The repository is written in Swift and ships as a Mac app, so the platform boundary is macOS only. The related searches for this project include "tomato bar windows", and the README gives no Windows or Linux path at all. Anyone outside macOS is not the target user.

One design decision is stated up front and is worth taking at face value: the app is "fully sandboxed with no entitlements". That constrains what it can do. It cannot read your calendar, cannot inspect which app is in the foreground, and cannot write outside its container. For a timer, that is a reasonable trade, and it is the reason the event log lives inside the app's container rather than in a shared location.

How the timer works: menu bar, notifications, hotkey, and a JSON log

The mechanism is conventional for a menu bar utility. The app runs as a menu bar item, holds the current interval state, and transitions between work and rest periods according to the configured durations. Sounds are optional, and notifications are described as actionable, meaning the notification itself carries the action rather than requiring you to open the menu.

The part that matters for anyone wiring TomatoBar into a larger workflow is the event log. According to the README, TomatoBar "logs state transitions in JSON format" to a fixed path inside its sandbox container:

~/Library/Containers/com.github.ivoronin.TomatoBar/Data/Library/Caches/TomatoBar.log

Because the file is JSON lines of state transitions rather than a rendered report, the intended use is downstream processing: the README says to "use this data to analyze your productivity and enrich other data sources". The README does not document the schema of those records, the exact set of transition types, or whether the file is rotated or truncated. If you plan to parse it, inspect it first rather than assuming a shape.

The second integration point is the URL scheme. TomatoBar responds to tomatobar:// URLs, and the README gives one concrete example, open tomatobar://startStop, for toggling the timer from the command line. That single verb is the only one the README names. Whether other verbs exist is not stated, so treat startStop as the documented surface and nothing more.

Installing TomatoBar with Homebrew and running a first session

The README offers two install routes: download the latest release from the GitHub releases page, or use Homebrew. The cask is the reproducible one.

brew install --cask tomatobar

After the install completes, TomatoBar appears in the menu bar. The README notes a fallback for the case where the app does not start: install with the --no-quarantine flag instead.

brew install --cask --no-quarantine tomatobar

That flag bypasses Gatekeeper quarantine on the downloaded app bundle, which is the usual cause of a first launch that silently does nothing. It is a real trade-off, not a cosmetic one: you are telling macOS to skip the check it would otherwise apply to a downloaded binary.

Once the icon is in the menu bar, the first useful action is to confirm the timer can be driven externally. The README's documented command is a toggle:

open tomatobar://startStop

Run it once and the timer should start; run it again and it should stop. If nothing happens, the URL scheme is not registered, which usually means the app is not running or the install did not complete. Next, do one full work interval and then check that the log file exists at the container path shown above. If it does, you have both integration points the README documents working at the same time.

Where TomatoBar stops: scope, sandbox and undocumented edges

The limitations follow from the design rather than from bugs. A sandboxed app with no entitlements cannot observe anything outside its container, so any feature that would require reading other applications, system idle time, or calendar events is out of reach by construction. If your idea of a Pomodoro tool includes automatic pause when you leave the keyboard, TomatoBar is the wrong tool and the README does not pretend otherwise.

The documented integration surface is also thin. One URL verb, startStop, and one log file with an undocumented record format. There is no CLI binary, no configuration file described in the README, and no API beyond the URL scheme. Settings are described as configurable intervals, sounds and notifications, but the README does not say where those settings are stored or whether they can be set outside the UI. Anyone hoping to version-control their Pomodoro configuration will not find a documented path for it.

The log file is the weakest documented point. It lives under Library/Caches, which is a directory macOS and cleanup tools are entitled to purge. The README does not say the log persists indefinitely, and it does not describe rotation. If you build a productivity dataset on that file, you own the copying step, and the README gives you no supported way to relocate the log.

Finally, version history matters here. The most recent release listed is a prerelease dated 2026-05-29, following v3.6.1 in February 2026. The last push to the repository was on 2026-05-29. The README also states that Touch Bar integration and macOS versions earlier than Big Sur are supported only by TomatoBar versions prior to 3.0, so older hardware and older systems are on a dead branch.

TomatoBar compared with a scripted timer or a calendar block

The obvious alternative is not another Pomodoro app but the shell. A short script using sleep and a notification command gives you arbitrary intervals, arbitrary labels, and output you fully control, with no app to install and no sandbox to work around. The difference in approach is where state lives: TomatoBar keeps the timer state in a menu bar process and exposes it through a URL scheme and a log file, while a script keeps it in the process you launched and writes wherever you tell it to.

The script wins on flexibility and on data ownership. It loses on the thing TomatoBar is actually built for: a visible, always-there control you can hit with a global hotkey without leaving the current window, plus notifications that are actionable rather than a terminal bell. Reimplementing that in shell is more work than it sounds, and it is work you would redo every time you change machines.

The second alternative is treating the Pomodoro interval as a calendar event. That approach gets you cross-device sync and a history you did not have to build, at the cost of the timer being a scheduled block rather than something you start on impulse. TomatoBar is the better fit when the decision to start a focus period happens in the moment. The calendar approach is better when you want the record of focus time to live where the rest of your schedule lives, and it works on every platform, which TomatoBar does not.

Maintenance, upgrade cost and the MIT licence

TomatoBar is MIT licensed. The repository contains a LICENSE file at the top level, and the README's own licence section covers something separate: the timer sounds, which are "licensed from buddhabeats". That distinction matters if you fork the project. The code is permissive, but the audio assets carry their own terms, and the README does not spell out what those terms are. Replacing the sounds is the straightforward way to avoid the question entirely. This is a description of what the repository states, not legal advice.

Upgrade cost is low in the normal case. Homebrew casks upgrade with a single command, and the app is sandboxed, so there is no system-wide configuration to migrate and no daemon to restart. The one thing to watch is the prerelease at the top of the release list. If you track the latest release rather than a tagged version, you are opting into prerelease builds, and the README says nothing about the stability of prerelease versus tagged releases. Pinning to v3.6.1 or another tagged version is the conservative choice for a machine you depend on.

There is no separate upgrade procedure documented for the log format. If a future version changes the JSON records, the README gives no compatibility statement, so any parser you write against that file should tolerate unknown fields rather than fail on them.

Editorial conclusion

Install TomatoBar if you want a Pomodoro timer that lives in the macOS menu bar, stays sandboxed with no entitlements, and can be driven from the command line through the tomatobar:// URL scheme. Skip it if you need a timer on Windows or Linux, or if you want task lists, statistics dashboards or team reporting; the README documents none of those. Before adopting it, check the release page for the version you intend to run, since the most recent release is a prerelease, and confirm that the log path ~/Library/Containers/com.github.ivoronin.TomatoBar/Data/Library/Caches/TomatoBar.log exists on your machine after the first session, because the README does not describe any fallback when logging fails.

Frequently asked questions

Official sources

1. Issues
2. ivoronin/TomatoBar on GitHub
3. License: MIT
4. README
5. Releases