Getting Started

Tomat (“tomato” in Swedish 🇸🇪) is a Pomodoro timer for Linux and macOS. It consists of a background service (daemon) that manages the timer state and a command-line client to control the timer and query its status.

If you are new to the Pomodoro technique, it is a time management method that breaks work into intervals (typically 25 minutes) separated by short breaks. This approach helps improve focus and productivity by encouraging regular breaks to rest and recharge.

graph TD
    A[25 min work] -->|Sessions 1-4| B[5 min break]
    B --> A
    A -->|Session 5| C[15 min long break]
    C --> A

An illustration of the Pomodoro technique.

Installation

The easiest way to install Tomat on Linux or macOS is with the install script:

curl --proto '=https' --tlsv1.2 -sSf https://jolars.github.io/tomat/install | sh

You can also use Cargo or a package manager:

cargo install tomat

# Arch Linux (AUR)
paru -S tomat-bin

See the installation guide for more options including DEB/RPM packages, NixOS, and building from source.

Basic Usage

The next step is to start the daemon:

tomat daemon start

After that, you can start a Pomodoro session by calling

tomat start

You can check the current status of the timer with:

tomat status

Which by default returns a JSON object suitable for Waybar integration:

{
  "text": "🍅 25:00 ⏸",
  "tooltip": "Work (2/4) - 25.0min (Paused)",
  "class": "work-paused",
  "percentage": 0.0
}

See the CLI Reference for a full list of commands and options.

Background Service Setup

Most users will want Tomat to start automatically on login. This command installs a systemd user service on Linux or a LaunchAgent on macOS:

tomat daemon install

On macOS, installation loads and starts the service immediately. On Linux, enable and start it with:

systemctl --user enable tomat.service --now

Status Bar Integration

The last step is to integrate Tomat with your status bar. To for instance set up Waybar, simply add the following module to your Waybar configuration:

{
  "modules-right": ["custom/tomat"],
  "custom/tomat": {
    "exec": "tomat status",
    "interval": 1,
    "return-type": "json",
    "format": "{text}",
    "tooltip": true,
    "on-click": "tomat toggle",
    "on-click-right": "tomat skip"
  }
}

The documentation features integration guides for several popular status bars, including Waybar, Polybar, and others.

Configuration

Tomat can be configured via $XDG_CONFIG_HOME/tomat/config.toml on Linux or ~/Library/Application Support/tomat/config.toml on macOS. Here is a basic example to get you started:

[timer]
work = 25.0
break = 5.0
long_break = 15.0
sessions = 4
auto_advance = "none"

See the Configuration Guide for a detailed explanation of all available configuration options

Architecture

Tomat uses a client–server architecture consisting of a daemon that runs in the background and a command-line client that sends commands to the daemon via a Unix socket. On Linux, this is normally $XDG_RUNTIME_DIR/tomat.sock; on macOS, it is stored beneath the per-user temporary directory.

graph TD
    A[Client] -->|Commands| B(Server)
    B -->|Status| A
    B -->|Notifications| C[Notification System]
    B -->|Sound| D[Sound System]

Overview of Tomat's architecture.

The purpose of this is to avoid having the timer be tied to the lifetime of the calling process, which allows several different clients to interact with the same timer instance and also prevents the need to save and restore states on status bar restarts.

The daemon is also responsible for sending desktop notification, sound alerts, and calling hooks.

Keyboard shortcuts