Tomat ("tomato" in Swedish 🇸🇪) is a Pomodoro timer for Linux, designed for seamless integration with waybar and other status bars.
- ⚙️ Easily Configurable: Persistent defaults via TOML configuration
- ⚡ Architecture: Client-server architecture that survives service restarts
- 📊 Flexible Ouput: Multiple output formats to support waybar, polybar, and others
- 📱 Notifications: Built-in desktop and sound notifications
The easiest way to get started is to download a pre-built binary from the latest release, or use your package manager if available.
# Download and install binary (Linux x86_64)
curl -L https://github.com/jolars/tomat/releases/latest/download/tomat-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv tomat /usr/local/bin/
# Or install from crates.io
cargo install tomat
# Start daemon and begin working
tomat daemon start
tomat start
# Check status
tomat status
The full documentation is available at https://jolars.github.io/tomat/.
Download pre-built binaries from the releases page:
- Generic Linux (x86_64, aarch64):
.tar.gzarchives - Debian/Ubuntu:
.debpackages - Fedora/RHEL:
.rpmpackages
# Example: Install generic binary for x86_64
curl -L https://github.com/jolars/tomat/releases/latest/download/tomat-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv tomat /usr/local/bin/
# Or install DEB package
curl -LO https://github.com/jolars/tomat/releases/latest/download/tomat_amd64.deb
sudo dpkg -i tomat_amd64.deb
# Or install RPM package
curl -LO https://github.com/jolars/tomat/releases/latest/download/tomat-x86_64.rpm
sudo rpm -i tomat-x86_64.rpm
# Using your favorite AUR helper
paru -S tomat-bin
# or
yay -S tomat-bin
If you are using NixOS, tomat is available in the official packages:
{
environment.systemPackages = [
pkgs.tomat
];
}
You still need to set up the systemd service for automatic startup. But if you're using home manager, you're in luck! Tomat is supported as a module:
{
services.tomat = {
enable = true;
settings = {
timer = {
work = 25;
break = 5;
};
};
};
}
cargo install tomat
On Linux systems, audio notifications require ALSA development libraries:
# Ubuntu/Debian
sudo apt-get install libasound2-dev
# Fedora/RHEL
sudo dnf install alsa-lib-devel
# Arch Linux
sudo pacman -S alsa-lib
Note: Audio will be automatically disabled if ALSA is not available. The timer will still work normally with desktop notifications only.
Most users will want to run the Tomat daemon as a systemd user service so that it starts automatically on login. Tomat provides a convenience command to install the service:
tomat daemon install
After that, you can enable and start the service with:
systemctl --user enable tomat.service --now
If you prefer to set up the systemd service manually, you can copy the service file from the examples directory:
# Manual systemd setup (if you prefer)
mkdir -p ~/.config/systemd/user
curl -o ~/.config/systemd/user/tomat.service https://raw.githubusercontent.com/jolars/tomat/main/assets/tomat.service
systemctl --user daemon-reload
systemctl --user enable tomat.service
systemctl --user start tomat.service
# Start with defaults (25min work, 5min break)
tomat start
# Custom durations
tomat start --work 30 --break 10 --long-break 20 --sessions 3
# Auto-advance through all phases
tomat start --auto-advance all
# Auto-advance only from work to break (forced breaks)
tomat start --auto-advance to-break
# Auto-advance only from break to work (self-paced work)
tomat start --auto-advance to-work
The timer is controlled through several tomat subcommands:
tomat status # Get current status (JSON for waybar)
tomat watch # Continuously output status updates
tomat toggle # Pause/resume timer
tomat skip # Skip to next phase
tomat stop # Stop timer and return to idle
The server (daemon) can be managed with tomat daemon <subcommand>:
tomat daemon start # Start background daemon
tomat daemon stop # Stop daemon
tomat daemon status # Check daemon status
tomat daemon install # Install systemd user service
tomat daemon uninstall # Remove systemd user service
To completely remove tomat, follow these steps:
# Stop and remove systemd service
tomat daemon uninstall
# Remove the binary
cargo uninstall tomat
# Remove configuration (optional)
rm -rf ~/.config/tomat
Tomat follows XDG Base Directory standards. Create
$XDG_CONFIG_HOME/tomat/config.toml (typically ~/.config/tomat/config.toml)
to customize defaults:
[timer]
work = 25.0 # Work duration in minutes
break = 5.0 # Break duration in minutes
long_break = 15.0 # Long break duration in minutes
sessions = 4 # Sessions until long break
auto_advance = "none" # Auto-advance mode: "none", "all", "to-break", "to-work"
[sound]
mode = "embedded" # Sound mode: "embedded", "system-beep", "none"
volume = 0.5 # Volume level (0.0-1.0)
[notification]
enabled = true # Enable desktop notifications
icon = "auto" # Icon mode: "auto", "theme", or custom path
timeout = 4000 # Notification timeout in milliseconds
[display]
text_format = "{icon} {time} {state}" # Text display format
# Available placeholders: {icon}, {time}, {state}, {phase}, {session}
# Examples:
# "{time}" -> "25:00"
# "{phase}: {time} {state}" -> "Work: 25:00 ▶"
# "[{session}] {icon} {time}" -> "[1/4] 🍅 25:00"
[hooks]
# Execute custom commands on timer events (optional)
# All hooks support these fields:
# cmd (required): Command to execute (absolute path recommended)
# args (optional): Array of arguments, default []
# timeout (optional): Timeout in seconds, default 5
# cwd (optional): Working directory, default $HOME
# capture_output (optional): Capture stdout/stderr for debugging, default false
#
# Available hooks:
# Phase transitions:
# on_work_start, on_work_end
# on_break_start, on_break_end
# on_long_break_start, on_long_break_end
# Timer control:
# on_pause, on_resume, on_stop, on_skip
#
# Environment variables passed to hooks:
# TOMAT_EVENT - Event name (e.g., "work_start", "pause")
# TOMAT_PHASE - Current phase ("work", "break", "long_break")
# TOMAT_REMAINING_SECONDS - Seconds remaining in current phase
# TOMAT_SESSION_COUNT - Current session number
# TOMAT_AUTO_ADVANCE - Auto-advance mode ("none", "all", "to-break", "to-work")
# Example hooks:
# [hooks.on_work_start]
# cmd = "notify-send"
# args = ["🍅 Work Time", "Focus for 25 minutes"]
#
# [hooks.on_break_start]
# cmd = "playerctl"
# args = ["pause"]
# timeout = 2
#
# [hooks.on_pause]
# cmd = "/home/user/scripts/dim-screen.sh"
# cwd = "/home/user"
💡 Tip: Copy the complete example config:
mkdir -p ~/.config/tomat
cp examples/config.toml ~/.config/tomat/config.toml
# Edit as needed
Add this to your waybar config (~/.config/waybar/config):
{
"modules-right": ["custom/tomat"],
"custom/tomat": {
"exec": "tomat status",
"interval": 1,
"return-type": "json",
"format": "{}",
"on-click": "tomat toggle",
"on-click-right": "tomat skip"
}
}
Add CSS styling (~/.config/waybar/style.css):
#custom-tomat.work {
background-color: #ff6b6b;
}
#custom-tomat.work-paused {
background-color: #ff9999;
}
#custom-tomat.break {
background-color: #4ecdc4;
}
#custom-tomat.break-paused {
background-color: #7dd3db;
}
#custom-tomat.long-break {
background-color: #45b7d1;
}
#custom-tomat.long-break-paused {
background-color: #74c0db;
}
💡 Tip: See examples/ for configuration examples for waybar
and other status bars.
By default, Tomat provides Waybar-optimized JSON output:
{
"text": "🍅 24:30 ▶",
"tooltip": "Work (1/4) - 25.0min",
"class": "work",
"percentage": 2.0
}
Output can be styled by using the CSS classes work, work-paused, break,
break-paused, long-break, and long-break-paused.
The output type can be changed via the -o (--output) flag, with options
waybar (default), i3status-rs, and plain.
# One-time setup
cargo install tomat
# Daily usage
tomat daemon start
tomat start # Begin 25min work session
# ... work on your task ...
tomat status # Check remaining time
tomat toggle # Take a quick pause
tomat skip # Move to break early
# ... enjoy your break ...
# Timer automatically suggests when to return to work
# Long focus session
tomat start --work 45 --break 15
# Sprint session with automatic progression
tomat start --work 15 --break 5 --auto-advance all
# Enforced breaks (auto-advance only to break)
tomat start --work 25 --break 5 --auto-advance to-break
# Self-paced work (auto-advance only to work)
tomat start --work 25 --break 5 --auto-advance to-work
# Deep work (no interruptions)
tomat start --work 90 --break 30 --sessions 2
# Return to configured defaults - just run start without flags
tomat start
Note: Custom durations only apply to the current session. Running
tomat start without flags will always use your configured defaults from
$XDG_CONFIG_HOME/tomat/config.toml (or built-in defaults if no config exists).
Contributions are welcome! See CONTRIBUTING.md for details.