{"id":37424666,"url":"https://github.com/jolars/tomat","last_synced_at":"2026-02-23T12:38:05.028Z","repository":{"id":321226345,"uuid":"1084965453","full_name":"jolars/tomat","owner":"jolars","description":"A Pomodoro timer for status bars","archived":false,"fork":false,"pushed_at":"2026-01-15T12:37:55.000Z","size":5553,"stargazers_count":22,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-16T20:09:20.588Z","etag":null,"topics":["life-hacks","pomodoro-timer","productivity","status-bar-tools","timer-clock","waybar"],"latest_commit_sha":null,"homepage":"https://jolars.github.io/tomat/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jolars.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"jolars"}},"created_at":"2025-10-28T12:07:06.000Z","updated_at":"2026-01-15T12:37:59.000Z","dependencies_parsed_at":"2025-10-28T15:21:11.812Z","dependency_job_id":"2514d7de-8f8e-4718-9ebf-936e513ca06b","html_url":"https://github.com/jolars/tomat","commit_stats":null,"previous_names":["jolars/tomat"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/jolars/tomat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jolars%2Ftomat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jolars%2Ftomat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jolars%2Ftomat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jolars%2Ftomat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jolars","download_url":"https://codeload.github.com/jolars/tomat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jolars%2Ftomat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28844011,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T07:39:25.367Z","status":"ssl_error","status_checked_at":"2026-01-28T07:39:24.487Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["life-hacks","pomodoro-timer","productivity","status-bar-tools","timer-clock","waybar"],"created_at":"2026-01-16T06:11:42.598Z","updated_at":"2026-02-23T12:38:05.020Z","avatar_url":"https://github.com/jolars.png","language":"Rust","funding_links":["https://github.com/sponsors/jolars"],"categories":[],"sub_categories":[],"readme":"# Tomat \u003cimg src='https://raw.githubusercontent.com/jolars/tomat/refs/heads/main/images/logo.svg' align=\"right\" width=\"139\" /\u003e\n\n[![Build Status](https://github.com/jolars/tomat/actions/workflows/build-and-test.yml/badge.svg?branch=main)](https://github.com/jolars/tomat/actions/workflows/build-and-test.yml)\n[![codecov](https://codecov.io/gh/jolars/tomat/graph/badge.svg?token=21Kx0unk2A)](https://codecov.io/gh/jolars/tomat)\n[![Crates.io](https://img.shields.io/crates/v/tomat.svg)](https://crates.io/crates/tomat)\n\nTomat (\"tomato\" in Swedish 🇸🇪) is a Pomodoro timer for Linux, designed for\nseamless integration with waybar and other status bars.\n\n## Features\n\n- **⚙️ Easily Configurable**: Persistent defaults via TOML configuration\n- **⚡ Architecture**: Client-server architecture that survives service restarts\n- **📊 Flexible Ouput**: Multiple output formats to support waybar, polybar, and\n  others\n- **📱 Notifications**: Built-in desktop and sound notifications\n\n## Quick Start\n\nThe easiest way to get started is to download a pre-built binary from the\n[latest release](https://github.com/jolars/tomat/releases/latest), or use your\npackage manager if available.\n\n```bash\n# Download and install binary (Linux x86_64)\ncurl -L https://github.com/jolars/tomat/releases/latest/download/tomat-x86_64-unknown-linux-gnu.tar.gz | tar xz\nsudo mv tomat /usr/local/bin/\n\n# Or install from crates.io\ncargo install tomat\n\n# Start daemon and begin working\ntomat daemon start\ntomat start\n\n# Check status\ntomat status\n```\n\n## Documentation\n\nThe full documentation is available at \u003chttps://jolars.github.io/tomat/\u003e.\n\n## Installation\n\n### Pre-built Binaries\n\nDownload pre-built binaries from the [releases page](https://github.com/jolars/tomat/releases/latest):\n\n- **Generic Linux** (x86_64, aarch64): `.tar.gz` archives\n- **Debian/Ubuntu**: `.deb` packages\n- **Fedora/RHEL**: `.rpm` packages\n\n```bash\n# Example: Install generic binary for x86_64\ncurl -L https://github.com/jolars/tomat/releases/latest/download/tomat-x86_64-unknown-linux-gnu.tar.gz | tar xz\nsudo mv tomat /usr/local/bin/\n\n# Or install DEB package\ncurl -LO https://github.com/jolars/tomat/releases/latest/download/tomat_amd64.deb\nsudo dpkg -i tomat_amd64.deb\n\n# Or install RPM package\ncurl -LO https://github.com/jolars/tomat/releases/latest/download/tomat-x86_64.rpm\nsudo rpm -i tomat-x86_64.rpm\n```\n\n### Package Managers\n\n#### Arch Linux (AUR)\n\n```bash\n# Using your favorite AUR helper\nparu -S tomat-bin\n# or\nyay -S tomat-bin\n```\n\n#### NixOS\n\nIf you are using NixOS, tomat is available in the official packages:\n\n```nix\n{\n  environment.systemPackages = [\n    pkgs.tomat\n  ];\n}\n```\n\nYou still need to set up the systemd service for automatic startup. But if\nyou're using home manager, you're in luck! Tomat is supported as a module:\n\n```nix\n{\n  services.tomat = {\n    enable = true;\n\n    settings = {\n      timer = {\n        work = 25;\n        break = 5;\n      };\n    };\n  };\n}\n```\n\n### Install from Crates.io\n\n```bash\ncargo install tomat\n```\n\n### Prerequisites for Building\n\nOn Linux systems, audio notifications require ALSA development libraries:\n\n```bash\n# Ubuntu/Debian\nsudo apt-get install libasound2-dev\n\n# Fedora/RHEL\nsudo dnf install alsa-lib-devel\n\n# Arch Linux\nsudo pacman -S alsa-lib\n```\n\n**Note**: Audio will be automatically disabled if ALSA is not available. The\ntimer will still work normally with desktop notifications only.\n\n## Systemd Service Setup\n\nMost users will want to run the Tomat daemon as a systemd user service so that\nit starts automatically on login. Tomat provides a convenience command to\ninstall the service:\n\n```bash\ntomat daemon install\n```\n\nAfter that, you can enable and start the service with:\n\n```bash\nsystemctl --user enable tomat.service --now\n```\n\n### Alternative Manual Setup\n\nIf you prefer to set up the systemd service manually, you can copy the service\nfile from the examples directory:\n\n```bash\n# Manual systemd setup (if you prefer)\nmkdir -p ~/.config/systemd/user\ncurl -o ~/.config/systemd/user/tomat.service https://raw.githubusercontent.com/jolars/tomat/main/assets/tomat.service\nsystemctl --user daemon-reload\nsystemctl --user enable tomat.service\nsystemctl --user start tomat.service\n```\n\n## Basic Usage\n\n### Start Timer\n\n```bash\n# Start with defaults (25min work, 5min break)\ntomat start\n\n# Custom durations\ntomat start --work 30 --break 10 --long-break 20 --sessions 3\n\n# Auto-advance through all phases\ntomat start --auto-advance all\n\n# Auto-advance only from work to break (forced breaks)\ntomat start --auto-advance to-break\n\n# Auto-advance only from break to work (self-paced work)\ntomat start --auto-advance to-work\n```\n\n### Control Timer\n\nThe timer is controlled through several `tomat` subcommands:\n\n```bash\ntomat status    # Get current status (JSON for waybar)\ntomat watch     # Continuously output status updates\ntomat toggle    # Pause/resume timer\ntomat skip      # Skip to next phase\ntomat stop      # Stop timer and return to idle\n```\n\n### Daemon Management\n\nThe server (daemon) can be managed with `tomat daemon \u003csubcommand\u003e`:\n\n```bash\ntomat daemon start     # Start background daemon\ntomat daemon stop      # Stop daemon\ntomat daemon status    # Check daemon status\ntomat daemon install   # Install systemd user service\ntomat daemon uninstall # Remove systemd user service\n```\n\n## Uninstall\n\nTo completely remove tomat, follow these steps:\n\n```bash\n# Stop and remove systemd service\ntomat daemon uninstall\n\n# Remove the binary\ncargo uninstall tomat\n\n# Remove configuration (optional)\nrm -rf ~/.config/tomat\n```\n\n## Configuration\n\nTomat follows XDG Base Directory standards. Create\n`$XDG_CONFIG_HOME/tomat/config.toml` (typically `~/.config/tomat/config.toml`)\nto customize defaults:\n\n```toml\n[timer]\nwork = 25.0           # Work duration in minutes\nbreak = 5.0           # Break duration in minutes\nlong_break = 15.0     # Long break duration in minutes\nsessions = 4          # Sessions until long break\nauto_advance = \"none\" # Auto-advance mode: \"none\", \"all\", \"to-break\", \"to-work\"\n\n[sound]\nmode = \"embedded\"     # Sound mode: \"embedded\", \"system-beep\", \"none\"\nvolume = 0.5          # Volume level (0.0-1.0)\n\n[notification]\nenabled = true        # Enable desktop notifications\nicon = \"auto\"         # Icon mode: \"auto\", \"theme\", or custom path\ntimeout = 4000        # Notification timeout in milliseconds\n\n[display]\ntext_format = \"{icon} {time} {state}\"  # Text display format\n# Available placeholders: {icon}, {time}, {state}, {phase}, {session}\n# Examples:\n#   \"{time}\"                    -\u003e \"25:00\"\n#   \"{phase}: {time} {state}\"   -\u003e \"Work: 25:00 ▶\"\n#   \"[{session}] {icon} {time}\" -\u003e \"[1/4] 🍅 25:00\"\n#\n# text_format_idle = \"\" # Optional: format for idle state (defaults to text_format)\n\n# Customize icons/symbols (optional)\n# [display.icons]\n# work = \"🍅\"          # Work/Idle phase icon\n# break = \"☕\"         # Break phase icon\n# long_break = \"🏖️\"   # Long break phase icon\n# play = \"▶\"          # Playing state symbol\n# pause = \"⏸\"         # Paused state symbol\n# stop = \"⏹\"          # Stopped/Idle state symbol\n\n[hooks]\n# Execute custom commands on timer events (optional)\n# All hooks support these fields:\n#   cmd (required): Command to execute (absolute path recommended)\n#   args (optional): Array of arguments, default []\n#   timeout (optional): Timeout in seconds, default 5\n#   cwd (optional): Working directory, default $HOME\n#   capture_output (optional): Capture stdout/stderr for debugging, default false\n#\n# Available hooks:\n#   Phase transitions:\n#     on_work_start, on_work_end\n#     on_break_start, on_break_end\n#     on_long_break_start, on_long_break_end\n#   Timer control:\n#     on_pause, on_resume, on_stop, on_skip\n#\n# Environment variables passed to hooks:\n#   TOMAT_EVENT - Event name (e.g., \"work_start\", \"pause\")\n#   TOMAT_PHASE - Current phase (\"work\", \"break\", \"long_break\")\n#   TOMAT_REMAINING_SECONDS - Seconds remaining in current phase\n#   TOMAT_SESSION_COUNT - Current session number\n#   TOMAT_AUTO_ADVANCE - Auto-advance mode (\"none\", \"all\", \"to-break\", \"to-work\")\n\n# Example hooks:\n# [hooks.on_work_start]\n# cmd = \"notify-send\"\n# args = [\"🍅 Work Time\", \"Focus for 25 minutes\"]\n#\n# [hooks.on_break_start]\n# cmd = \"playerctl\"\n# args = [\"pause\"]\n# timeout = 2\n#\n# [hooks.on_pause]\n# cmd = \"/home/user/scripts/dim-screen.sh\"\n# cwd = \"/home/user\"\n```\n\n**💡 Tip**: Copy the complete example config:\n\n```bash\nmkdir -p ~/.config/tomat\ncp examples/config.toml ~/.config/tomat/config.toml\n# Edit as needed\n```\n\n## Waybar Integration\n\nAdd this to your waybar config (`~/.config/waybar/config`):\n\n```json\n{\n  \"modules-right\": [\"custom/tomat\"],\n  \"custom/tomat\": {\n    \"exec\": \"tomat status\",\n    \"interval\": 1,\n    \"return-type\": \"json\",\n    \"format\": \"{}\",\n    \"on-click\": \"tomat toggle\",\n    \"on-click-right\": \"tomat skip\"\n  }\n}\n```\n\nAdd CSS styling (`~/.config/waybar/style.css`):\n\n```css\n#custom-tomat.work {\n  background-color: #ff6b6b;\n}\n#custom-tomat.work-paused {\n  background-color: #ff9999;\n}\n#custom-tomat.break {\n  background-color: #4ecdc4;\n}\n#custom-tomat.break-paused {\n  background-color: #7dd3db;\n}\n#custom-tomat.long-break {\n  background-color: #45b7d1;\n}\n#custom-tomat.long-break-paused {\n  background-color: #74c0db;\n}\n```\n\n**💡 Tip**: See [`examples/`](examples/) for configuration examples for waybar\nand other status bars.\n\n## Output\n\nBy default, Tomat provides Waybar-optimized JSON output:\n\n```json\n{\n  \"text\": \"🍅 24:30 ▶\",\n  \"tooltip\": \"Work (1/4) - 25.0min\",\n  \"class\": \"work\",\n  \"percentage\": 2.0\n}\n```\n\nOutput can be styled by using the CSS classes `work`, `work-paused`, `break`,\n`break-paused`, `long-break`, and `long-break-paused`.\n\nThe output type can be changed via the `-o` (`--output`) flag, with options\n`waybar` (default), `i3status-rs`, and `plain`.\n\n## Examples\n\n### Basic Workflow\n\n```bash\n# One-time setup\ncargo install tomat\n\n# Daily usage\ntomat daemon start\ntomat start          # Begin 25min work session\n# ... work on your task ...\ntomat status         # Check remaining time\ntomat toggle         # Take a quick pause\ntomat skip           # Move to break early\n# ... enjoy your break ...\n# Timer automatically suggests when to return to work\n```\n\n### Custom Sessions\n\n```bash\n# Long focus session\ntomat start --work 45 --break 15\n\n# Sprint session with automatic progression\ntomat start --work 15 --break 5 --auto-advance all\n\n# Enforced breaks (auto-advance only to break)\ntomat start --work 25 --break 5 --auto-advance to-break\n\n# Self-paced work (auto-advance only to work)\ntomat start --work 25 --break 5 --auto-advance to-work\n\n# Deep work (no interruptions)\ntomat start --work 90 --break 30 --sessions 2\n\n# Return to configured defaults - just run start without flags\ntomat start\n```\n\n**Note**: Custom durations only apply to the current session. Running\n`tomat start` without flags will always use your configured defaults from\n`$XDG_CONFIG_HOME/tomat/config.toml` (or built-in defaults if no config exists).\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjolars%2Ftomat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjolars%2Ftomat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjolars%2Ftomat/lists"}