tomat 2.0.0

A Pomodoro timer with daemon support for waybar and other status bars
tomat-2.0.0 is not a library.

Tomat

Build Status License: MIT

Tomat ("tomato" in Swedish 🇸🇪) is a Pomodoro timer with daemon support designed for 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
  • 🔊 Sound Notifications: Audio alerts enabled by default 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

# Optional: Configure defaults in ~/.config/tomat/config.toml

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.

Quick Install (Recommended)

# Install from crates.io
cargo install tomat

# Set up systemd service for auto-start
mkdir -p ~/.config/systemd/user
curl -o ~/.config/systemd/user/tomat.service https://raw.githubusercontent.com/jolars/tomat/main/tomat.service
systemctl --user daemon-reload
systemctl --user enable tomat.service
systemctl --user start tomat.service

Note: Ensure ~/.cargo/bin is in your PATH.

Install from Source

# Clone and install
git clone https://github.com/jolars/tomat.git
cd tomat
./install.sh

This installs the binary and sets up the systemd service automatically.

Manual Installation

# Install from crates.io or build from source
cargo install tomat
# OR
cargo install --path .

# Set up systemd service
mkdir -p ~/.config/systemd/user
cp tomat.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable tomat.service
systemctl --user start tomat.service

Note: Ensure ~/.cargo/bin is in your PATH.

Configuration

Tomat can be configured using a TOML file located at ~/.config/tomat/config.toml. This allows you to set default values for timer durations and behaviors without specifying them on every command.

Sound Notifications

By default, tomat plays audio notifications when transitioning between work/break phases:

  • Embedded sounds: High-quality WAV files built into the application
  • Linux requirement: Requires ALSA (Advanced Linux Sound Architecture)
  • Automatic fallback: If audio system unavailable, falls back to system beep or disables audio
  • Customizable: Override with your own sound files or disable entirely
  • Volume control: Adjustable volume level (0.0 to 1.0)

To disable audio notifications:

[sound]
enabled = false

To use custom sound files:

[sound]
work_to_break = "/path/to/your/work-end-sound.wav"
break_to_work = "/path/to/your/break-end-sound.wav"
work_to_long_break = "/path/to/your/long-break-start.wav"

Example Configuration

Create ~/.config/tomat/config.toml:

[timer]
work = 25.0        # Work duration in minutes (default: 25)
break = 5.0        # Break duration in minutes (default: 5)
long_break = 15.0  # Long break duration in minutes (default: 15)
sessions = 4       # Sessions until long break (default: 4)
auto_advance = false # Auto-advance between phases (default: false)

[sound]
enabled = true       # Enable sound notifications (default: true)
system_beep = false  # Use system beep instead of WAV files (default: false)
use_embedded = true  # Use embedded sounds (default: true)
volume = 0.5         # Volume level 0.0-1.0 (default: 0.5)
# Custom sound files (optional - override embedded sounds)
# work_to_break = "/path/to/work-to-break.wav"
# break_to_work = "/path/to/break-to-work.wav"
# work_to_long_break = "/path/to/work-to-long-break.wav"

Priority Order

Settings are applied in this order (later overrides earlier):

  1. Built-in defaults: 25min work, 5min break, 15min long break, 4 sessions
  2. Config file: Values from ~/.config/tomat/config.toml
  3. CLI arguments: Flags passed to tomat start

Partial Configuration

You can specify only the values you want to override:

[timer]
work = 30.0
auto_advance = true
# Other values will use built-in defaults

[sound]
enabled = false  # Disable all sound notifications
# Other sound settings will use built-in defaults

Usage

Daemon Management

# Start daemon in background
tomat daemon start

# Check daemon status
tomat daemon status

# Stop daemon
tomat daemon stop

Timer Control

# Start Pomodoro (25min work, 5min break by default)
tomat start

# Start with custom durations and auto-advance
tomat start --work 30 --break 10 --auto-advance

# Toggle pause/resume
tomat toggle

# Skip to next phase
tomat skip

# Stop current session
tomat stop

# Get status (JSON for waybar)
tomat status

Auto-advance Behavior

By default (--auto-advance=false):

  • Timer transitions to next phase but pauses
  • You manually resume with tomat toggle or tomat start
  • Gives you control over when breaks start/end

With --auto-advance=true:

  • Timer automatically continues through all phases
  • No manual intervention needed
  • Traditional Pomodoro timer behavior

Waybar Integration

Configuration

Add to your waybar config:

"custom/pomodoro": {
    "format": "{}",
    "exec": "tomat status",
    "return-type": "json",
    "interval": 1,
    "on-click": "tomat toggle",
    "on-click-right": "tomat skip",
    "on-click-middle": "tomat start"
}

Styling

The status output provides CSS classes for styling:

#custom-pomodoro.work {
  background: #2d5a27;
  color: #ffffff;
}

#custom-pomodoro.work-paused {
  background: #1a3a16;
  color: #cccccc;
}

#custom-pomodoro.break {
  background: #8b4513;
  color: #ffffff;
}

#custom-pomodoro.break-paused {
  background: #5c2e09;
  color: #cccccc;
}

#custom-pomodoro.long-break {
  background: #1e3a8a;
  color: #ffffff;
}

#custom-pomodoro.long-break-paused {
  background: #0f1e5c;
  color: #cccccc;
}

Output Format

The tomat status command returns JSON optimized for status bars:

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

Visual Indicators

  • Icons: 🍅 (work), ☕ (break), 🏖️ (long break)
  • State: ▶ (running), ⏸ (paused)
  • Format: {icon} {time} {state}

CSS Classes

  • work / work-paused - Work session running/paused
  • break / break-paused - Break session running/paused
  • long-break / long-break-paused - Long break running/paused

Architecture

┌─────────────────┐    Unix Socket     ┌──────────────────┐
│   tomat start   │ ──────────────────▶│   tomat daemon   │
│   tomat status  │                    │                  │
│   tomat toggle  │ ◀──────────────────│  Timer State     │
│   tomat stop    │    JSON Response   │  Notifications   │
└─────────────────┘                    └──────────────────┘
     (Client)                              (Background)
  • Daemon: Runs continuously, manages timer state and notifications
  • Client: Sends commands via Unix socket ($XDG_RUNTIME_DIR/tomat.sock)
  • Persistence: Timer survives waybar restarts and system suspend/resume

Examples

Basic Workflow

# Start daemon
tomat daemon start

# Begin a Pomodoro session
tomat start --work 25 --break 5

# Status shows: 🍅 24:30 ▶
tomat status

# Pause for interruption
tomat toggle
# Status shows: 🍅 24:30 ⏸

# Resume work
tomat toggle
# Status shows: 🍅 24:29 ▶

# When work completes (auto_advance=false default)
# Status shows: ☕ 05:00 ⏸

# Start break manually
tomat toggle
# Status shows: ☕ 04:59 ▶

Automatic Mode

# Start with auto-advance (no manual resume needed)
tomat start --work 25 --break 5 --auto-advance

# Timer automatically flows: Work ▶ → Break ▶ → Work ▶ → ...
# No manual intervention required

Development

See CONTRIBUTING.md for detailed development documentation.

# Quick development workflow
cargo build
tomat daemon start
tomat start --work 0.1 --break 0.05  # Fast testing
cargo test  # Run 11 integration tests

License

MIT License - see the LICENSE file.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make changes with tests
  4. Run cargo test and cargo clippy
  5. Submit a pull request

Bug reports and feature requests welcome via GitHub Issues.