Focus Timer: pomodoro timing for GNOME, built in Vala

Installing from Flathub is the path the project recommends

The README puts the Flatpak install first and calls it recommended, which is a reasonable instruction for an app whose whole point is fitting into a running desktop. Two commands get you there:

flatpak install flathub io.github.focustimerhq.FocusTimer
flatpak run io.github.focustimerhq.FocusTimer

The application id, `io.github.focustimerhq.FocusTimer`, follows the GNOME convention of a reverse domain name tied to the project site, and it is also the name used for the Flatpak sandbox, the desktop file and the development manifest in the repository root. That consistency is a small sign of a project that has thought about packaging rather than treating it as an afterthought.

There is one packaging consequence worth reading twice, because it changes what the app can do. The Flathub build cannot run custom scripts, which the README identifies as the Automation panel in the Preferences window. A timer that fires commands on session transitions is a different tool from one that only counts, so if the automation panel matters to you, the Flathub route is the wrong one.

Building from source takes a meson setup and two ninja calls

The source instructions name the build prerequisites plainly: meson, ninja, and the development headers for GLib and GTK. The clone step uses the repository URL with a shortened directory name:

git clone https://github.com/focustimerhq/FocusTimer.git focus-timer
cd focus-timer

Then the build itself:

meson setup build --prefix=/usr
ninja -C build
sudo ninja -C build install

The binary that gets installed is called `focus-timer`, which differs from the repository and application names. Once installed you launch it with the same short name. Uninstalling is a `ninja -C build uninstall` under sudo, and the README makes a point of mentioning that step rather than leaving it to your package manager.

The build layout is what you would expect from a mature GTK project. There is a `meson.build` at the root, a `meson_options.txt` for optional features, `po/` for translations, `tests/` for the test suite, and a `lint/` directory next to a `run-vala-lint.sh` script, which tells you the project lints its own source as part of day to day work rather than treating style as something to fix at release time.

A Vala codebase small enough to read end to end

The language is Vala, and the top level of the tree is short. Beyond the build files and documentation, the entries that matter are `src/` for the application itself, `data/` for icons and desktop files, `vapi/` alongside a root `config.vapi`, `po/` for translations, `tests/`, and `focus-timer.doap` for the standard project description file. There is no directory of vendored dependencies in the listing, which is consistent with a project that leans on system libraries rather than shipping a web runtime.

That size is the honest reason to pay attention. A timer app does not need a large codebase, and if you want to know exactly what happens when a session ends, the answer is a short walk through `src/` rather than a documentation site. The presence of `tests/` next to the source suggests the behaviour is at least partially pinned down, and the presence of `po/` says the maintainers expect translations from outside contributors.

The project has a public history as gnome-pomodoro and now as Focus Timer, and the repository reflects a rename rather than a rewrite: the code, the build system and the test layout are those of the older app with a new identity and a new application id.

Statistics land in a SQLite file you can go and look at

The feature list includes daily, weekly and monthly statistics, and the migration note explains where the data lives. When the app was called gnome-pomodoro the database sat at `~/.local/share/gnome-pomodoro/database.sqlite`, and moving to the new app means copying that file into the Flatpak sandbox at `~/.var/app/io.github.focustimerhq.FocusTimer/data/focus-timer/database.sqlite`. A SQLite file per user is a deliberate choice, and it means your history is inspectable with ordinary tools rather than trapped in a proprietary store.

The screenshots confirm the shape of the reporting: separate views for daily and monthly figures rather than a single dashboard. Monthly totals are the interesting half, because a pomodoro method only helps if you can see whether the weeks where you felt productive actually contained more focused sessions than the ones where you did not.

Session and break lengths are configurable, and the README lists customizable work session and break lengths as the first feature. Customizable lengths matter more than they sound, because a 25 minute default is a starting point from the Pomodoro Technique rather than a law, and people who work in long research blocks usually end up running longer sessions with shorter breaks.

Shell commands, D-Bus and a CLI as the extension points

The extension story is the most interesting thing in the feature list: the app is extensible via custom shell commands, D-Bus, and a CLI. The three together cover the three ways a Linux desktop app usually gets wired into the rest of a system. Shell commands are the blunt instrument, useful for launching a music player or blocking a site at the end of a work session. D-Bus is the programmatic route, letting another application query or drive the timer. The CLI is what you would use from a script or a keyboard binding.

The Automation panel in Preferences is where the shell command side of this lives, and it is the feature that the Flathub package leaves out. That pairing of a documented extension surface with a package that removes part of it is worth keeping in mind: if the automation panel is why you are interested, build from source.

The README also points to a separate GNOME Shell extension, gnome-shell-extension-focus-timer, for deeper desktop integration. Splitting that out is a sensible boundary, because a shell extension has to survive GNOME version bumps and run inside the compositor process, which is a different maintenance burden from an ordinary application. It also means the core app can work on GNOME, Xfce, or any other desktop that speaks the same toolkit.

What the README settles and what it leaves open

The README is thorough about installation, packaging and support, and it links a troubleshooting section in CONTRIBUTING.md that explains how to check logs before filing a bug. That is a good sign, because log hunting is where most GNOME bug reports end up. Support pointers cover the issue tracker, a feature request path, and a discussions page.

What it does not provide is much about the timer logic itself. There is no description of how interruptions are counted, whether a paused session is recorded, or how the daily rollover works, and the repository carries no release history in its metadata to suggest how quickly the app changes. Version numbers appear in the screenshot URLs for the 1.1 series, so 1.1 is a real line, but the README does not explain what changed in it.

The licensing and trademark notices deserve a note too. The code is GPL 3, and the README states plainly that the project is not affiliated with or approved by the GNOME Foundation, and that Pomodoro and Pomodoro Technique are registered trademarks of Francesco Cirillo. That is a careful reading of a name that other software also uses. For a GPL application distributed on Flathub, the licence and the trademark note together answer most of what a packager needs to know.

Editorial conclusion

Focus Timer is at its best when you want a timer that already belongs to the desktop instead of another window to keep on top. The tray indicator, the break overlay and the global hotkeys are the parts a GNOME session actually uses, and the automation hooks mean the timer can drive other tools when you want it to. The caveats are equally concrete: the Flathub build cannot run custom scripts, the tree is small enough to read in an afternoon, and the feature list in the README is the whole scope. Start from the Flathub install, turn on the break overlay, and only reach for the meson build if you need to change the panel.

Frequently asked questions

Official sources

1. focustimerhq/FocusTimer on GitHub
2. Issues
3. License: GPL-3.0
4. Project website
5. README