Tomat

Tomat ("tomato" in Swedish 🇸🇪) is a Pomodoro timer for Linux, designed for seamless integration with waybar and other status bars.

Features

• 🍅 Pomodoro Technique: Work/break cycles with configurable durations
• ⚙️ TOML Configuration: Persistent defaults via XDG config directory
• ⚡ Daemon Architecture: Robust background service that survives restarts
• 📊 Waybar Integration: JSON output with CSS classes for seamless integration
• 🎮 Visual Indicators: Play ▶ and pause ⏸ symbols for clear state indication
• 🔧 Auto-advance Control: Choose between manual or automatic phase transitions
• 🔄 Process Management: Built-in daemon start/stop/status commands
• 🖥️ Unix Sockets: Fast, secure local communication
• 🌙 Systemd Integration: Auto-start with user session
• 📱 Desktop Notifications: Phase transition alerts with configurable icons
• 🖼️ Icon System: Embedded icon with mako compatibility and custom icon support
• 🔊 Sound Notifications: Audio alerts with embedded sounds and customization
• 💾 Minimal Resources: Lightweight and efficient

Quick Start

# Install from crates.io
cargo install tomat

# Start daemon and begin working
tomat daemon start
tomat start

# Check status (perfect for waybar)
tomat status

Installation

Prerequisites

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.

Install from Crates.io

cargo install tomat

Quick Setup with Systemd

After installing tomat, you can set up the systemd service with a single command:

# Install systemd user service (recommended)
tomat daemon install

# Start the daemon
systemctl --user start tomat.service

Alternative manual setup:

# 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/examples/systemd.service
systemctl --user daemon-reload
systemctl --user enable tomat.service
systemctl --user start tomat.service

Basic Usage

Start Timer

# Start with defaults (25min work, 5min break)
tomat start

# Custom durations
tomat start --work 30 --break 10 --long-break 20 --sessions 3

# Auto-advance between phases
tomat start --auto-advance

Control Timer

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

Daemon Management

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

Uninstall

To completely remove tomat:

# Stop and remove systemd service
tomat daemon uninstall

# Remove the binary
cargo uninstall tomat

# Remove configuration (optional)
rm -rf ~/.config/tomat

Configuration

Create ~/.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 = false # Auto-continue to next phase

[sound]
enabled = true       # Enable sound notifications
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"

💡 Tip: Copy the complete example config:

mkdir -p ~/.config/tomat
cp examples/config.toml ~/.config/tomat/config.toml
# Edit as needed

Waybar Integration

Add to your waybar config (~/.config/waybar/config):

Option 1: Polling with status (recommended for most users)

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

Option 2: Continuous updates with watch

For reduced CPU usage, use the watch command instead:

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

Note: The watch command maintains a single connection to the daemon and updates at the specified interval (default: 1 second). It automatically exits when the daemon stops.

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.

Output

By default, Tomat provides waybar-optimized JSON output:

{
  "text": "🍅 24:30 ▶",
  "tooltip": "Work (1/4) - 25.0min",
  "class": "work",
  "percentage": 2.0
}

Outupt 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.

Documentation

For detailed guides and advanced configuration:

• 📋 Documentation Index - Complete documentation overview
• 📁 Examples - Ready-to-use configurations (waybar, systemd, etc.)
• 📖 Configuration Guide - Complete configuration options
• 🔗 Integration Guide - Waybar, systemd, and notification setup
• 🐛 Troubleshooting - Common issues and solutions

Examples

Basic Workflow

# 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

Custom Sessions

# Long focus session
tomat start --work 45 --break 15

# Sprint session
tomat start --work 15 --break 5 --auto-advance

# Deep work (no interruptions)
tomat start --work 90 --break 30 --sessions 2

Architecture

Tomat uses a client-daemon architecture with Unix socket communication to allow fast and reliable interactions, with persistent timer state managed by the daemon.

Client Commands  →  Unix Socket  →    Daemon   →  Timer State    →    Output
     ↓                  ↓               ↓              ↓                 ↓
tomat start      $XDG_RUNTIME_DIR/  Background     Work/Break/   {"text": "🍅 25:00 ▶",
tomat status     tomat.sock         Service        LongBreak      "class": "work"}
tomat toggle                                       Phases

• Daemon: Runs continuously, manages timer state and notifications
• Client: Sends commands via Unix socket
• Persistence: Timer survives waybar restarts and system suspend/resume
• Notifications: Desktop alerts and optional sound notifications on phase transitions

Contributing

Contributions are welcome! See CONTRIBUTING.md for details.