🍅 Pomati - A Pomodoro Timer for a Terminal

Pomati is a Pomodoro timer made for tiling window managers. It is designed to run in a customized terminal configuration that provides a large clock in a 'scratchpad' window. It is operated with minimal keystrokes and with minimal visual distraction.

• Features
• Installation
  • On Arch with AUR package
  • From Source
    • Prerequisites
    • Compiling
• Usage
  • Starting the Timer
  • Key Bindings
  • Command-Line Flags
  • Commands
    • pomati stats
    • pomati reset
• Configuration
  • Tagging
  • Tag Triggers
• Syncing Data Across Machines
  • Sync Prerequisites
  • pompush - Push Data to Remote Host
  • pompull - Pull Data from Remote Host
  • What Gets Synced
• Window Managers' Settings
  • Hyprland v0.53
  • Qtile v0.34
• Development
  • Development Prerequisites
  • Getting Started
  • Common Commands
• Author
• Artificial Intelligence policy
• License

Features

• Pomodoro Workflow: Work, short break, long break cycles.
• Terminal-Based Interface: Tiling window managers friendly.
• Session Tagging: Categorize your pomodoros with tags for better tracking.
• Timezone-Aware: Stats are displayed in your current local timezone, regardless of where sessions were completed.
• Desktop Notifications: Get notified when a timer is up.
• Sound Alerts: Optional sound alerts to signal the end of a session.
• Session Statistics: Track your progress with daily and monthly stats, including tag breakdowns.
• Customizable Timers: Adjust the duration of work and break intervals.
• Tag Triggers: Automatic tag change by IP, hostname, time (optional).
• Cross-Platform: Works on Linux and macOS.

Timer

Stats

Installation

On Arch with AUR package

yay -S pomati

From Source

Prerequisites

• Go 1.25 or later.
• just (a command runner): https://github.com/casey/just

Compiling

go install codeberg.org/dimus/pomati@latest

or

git clone https://codeberg.org/dimus/pomati.git
cd pomati
just install

This will install the pomati binary to your Go bin directory ($GOPATH/bin).

Usage

Starting the Timer

To quick test run:

pomati

However I think it is much better to run it using a custom terminal configuration (example configurations are created in $HOME/.config/pomati after you run pomati for the first time.

alacritty --config-file ~/.config/pomati/alacritty.toml -e pomati
ghostty --config-file=~/.config/pomati/ghostty.conf -e pomati
kitty --config ~/.config/pomati/kitty.conf -e pomati

(Also see Window Managers` Settings section for examples of Hyprland and Qtile configurations)

The timer shows

• Optional One-letter tag (e.g., h for home, w for work)
• A countdown timer
• The current session type (Work, Short Break, or Long Break)
• The number of completed tomatoes today

The timer follows the classic Pomodoro pattern:

• 25-minute work sessions (default)
• 5-minute short breaks after each session
• 15-minute long break after every 4th completed session

Key Bindings

The timer suppose to run in a 'scratch' window, to make it easier to hide/show when needed. But running in a workspace is also possible, just less convenient.

When a timer expires, you'll receive a desktop notification and sound alert. Use scratchpad shortcut to show the timer, press Enter to acknowledge the state transition and continue to the next session.

To pause timer press p.

To quit timer press q (or just close the terminal).

To switch a tag press Ctrl-<tag> for example for work w tag press Ctrl-w.

If you configured tag triggers, they can be toggled with t (see below).

Command-Line Flags

You can customize the timer with these flags:

pomati [flags]

Available flags:

• -c, --clock-color <color>: Set the timer clock color. Accepts terminal color numbers (e.g., 210) or RGB hex codes (e.g., #ac8, #eab920)
• -V, --version: Display version information
• -h, --help: Show help information

Examples:

# Start timer with custom clock color
pomati --clock-color 210
# Start timer with hex color
pomati -c "#eab920"

Commands

pomati stats

Display statistics about your completed Pomodoro sessions:

pomati stats

By default, this shows:

• Daily stats for the last 30 days with tomato emoji graphs and tag breakdowns
• Monthly stats for the last 3 months with tag breakdowns
• Summary statistics (total sessions, average per day, best day)

Timezone Handling:

Statistics are always displayed in your current local timezone. If you complete pomodoros in one timezone and view stats from another, the dates and times are automatically adjusted to your current location. For example, a session completed at 11:30 PM EST will appear in the correct local day when viewed from PST.

Available flags:

• -d, --days <number>: Number of days to show for daily stats (default: 30)
• -a, --all: Show all months instead of just the last 3
• -n, --no-graph: Show only summary without graphs
• -j, --json: Output stats as JSON

Examples:

# Show last 7 days only
pomati stats -d 7
# Show all historical data without graphs
pomati stats --all --no-graph
# Export stats as JSON
pomati stats --json

pomati reset

Remove all Pomati data and configuration:

pomati reset

This deletes:

• Configuration file (~/.config/pomati/pomati.yaml)
• Session history database (~/.local/share/pomati/pomati.db)
• Log files

Warning: This action cannot be undone.

Configuration

On the first run, Pomati will create a default configuration file at ~/.config/pomati/pomati.yaml. You can customize the following settings:

Tagging

Pomati supports tagging your work sessions to categorize and track different types of work. Tags appear in the timer display and in statistics breakdowns.

Setting a Default Tag:

Add a default_tag to your pomati.yaml:

default_tag:"w"

Defining Custom Tags:

You can define tags with descriptions and emojis in your pomati.yaml:

tags:w:desc:"Work tasks"emoji:"💼"s:desc:"Learning and study"emoji:"📚"p:desc:"Personal projects"emoji:"🏠"

How Tags Work:

• When you start a new work session, it uses:
  1. The tag from your previous completed session, or
  2. The default_tag if configured, or
  3. No tag (empty string)
• Tags are displayed in the timer window: w 25:00 wrk 0t
• Tags persist across sessions until you complete a tomato with a different tag
• Tag statistics show which tags you used most on each day/month

Each tag is automatically assigned a Ctrl-<tag> shorctut. For example, to switch to work tag w use shortcut Ctrl-w

Tag Triggers

Tags can be set to switch automatically if environment changes. Tag triggers can be configured to detect changes in IP, hostname, or timespan. For example, if you only do work-related stuff from 9:00 to 17:00, tag can be configured to automatically change to w during that time period. If user moves from one computer to another the timer can be moved to another machine, and changes in IP or hostname can also trigger a change in the tag.

Configuring Tag Triggers:

Add triggers inside your tag definitions in pomati.yaml:

tags:w:desc:"Work tasks"emoji:"💼"triggers:ips:["192.168.1.0/24","10.0.0.0/8"]hosts:["work-laptop"]times:["09:00-17:00"]p:desc:"Personal projects"emoji:"🏠"triggers:hosts:["home-desktop"]times:["17:00-23:00"]s:desc:"Learning and study"emoji:"📚"triggers:times:["06:00-09:00"]

Each tag's triggers can specify:

• ips: Array of IP addresses
• hosts: Array of hostnames
• times: Array of time ranges in 24-hour format

Within a tag, all specified arrays use OR logic (any match activates). Press t to toggle automatic tag triggers on/off during a session.

Syncing Data Across Machines

Pomati includes helper scripts to synchronize your session history and configuration across multiple computers using rsync over SSH. This allows you to switch between machines still keeping the same state.

Sync Prerequisites

• SSH access to the remote machine
• SSH key authentication configured (password authentication not supported)
• rsync installed on both machines

pompush - Push Data to Remote Host

Push your local Pomati data and configuration to a remote machine:

scripts/pompush [OPTIONS] <hostname>

Available options:

• -n, --dry-run: Show what would be transferred without making changes
• -q, --quiet: Suppress non-error output
• -h, --help: Display help message

Examples:

# Push to a remote server
scripts/pompush mydesktop
# Preview changes without syncing
scripts/pompush --dry-run 192.168.1.100

pompull - Pull Data from Remote Host

Pull Pomati data and configuration from a remote machine to your local system:

scripts/pompull [OPTIONS] <hostname>

Available options:

• -n, --dry-run: Show what would be transferred without making changes
• -q, --quiet: Suppress non-error output
• -h, --help: Display help message

Examples:

# Pull from a remote server
scripts/pompull myserver.local
# Preview changes without syncing
scripts/pompull --dry-run workstation

Note: pompull and pompush use rsync's --delete flag, which assures that source and target have exactly the same files.

What Gets Synced

Both scripts synchronize:

• Session history database: ~/.local/share/pomati/pomati.db
• Configuration file: ~/.config/pomati/pomati.yaml
• Log files: ~/.local/share/pomati/pomati.log

Window Managers' Settings

Here are examples how to set pomati with Hyprland and Qtile.

Hyprland v0.53

I think the best way to use Pomati with Hyprland is by setting it in a special workspace, a scratchpad analog of Hyprland. This way its terminal window is always available, and pomati will continue running when it is hidden.

First you need to create a shortcut

bind = SUPER, X, togglespecialworkspace, pomspace

This setting binds SUPER+X to open special workspace named pomspace. Now lets create this pomspace:

## POMATI
workspace = special:pomspace, on-created-empty:alacritty \
 --config-file $HOME/.config/pomati/alacritty.toml -e /usr/bin/pomati
windowrule {
 name = pomati
 match:workspace = special:pomspace
 float = on
 center = on
 size = monitor_w*0.9 155
}

This setting starts pomati timer in a special workspace named pomspace and opens it in a window that is centered on the screen. Note that configuration syntax of Hyprland is still not settled, so if these settiings do not work with your version of Hyprland, go to [Hyprland Wiki] to find current syntax.

Qtile v0.34

Qtile also has a scratchpad functionality. To set it up, first create a key binding:

[Key(["mod4"], "x", lazy.group["scratchpad"].dropdown_toggle("pomati"))

The "mod4" key in Qtile usually corresponds to SUPER. So this command also sets SUPER+X shorcut to toggle visibility of a scratchpad "pomati"

 dropdowns = [
 DropDown(
 "pomati",
 "alacritty -t pomati --config-file "
 "/path/to/.config/pomati/alacritty.toml -e '/usr/bin/pomati'",
 x=0.05,
 y=0.01,
 width=0.9,
 height=0.15,
 on_focus_lost_hide=False,
 ),
 ...
 ]

Development

Development Prerequisites

• Go 1.25.1 or later.
• just (a command runner): https://github.com/casey/just

Getting Started

1. Clone the repository:

   git clone https://codeberg.org/dimus/pomati.git
   cd pomati
   

2. Install dependencies:

   go mod tidy
   

Common Commands

The Justfile in the root of the project provides several useful commands for development:

• just build: Build the binary.
• just install: Install the binary to your Go bin directory.
• just test: Run the tests.
• just fmt: Format the code.
• just lint: Run the linter.
• just verify: Run all checks (format, tidy, test, build).

Author

dimus

Artificial Intelligence policy

Claude Code was used sporadically for writing documentation, planning, finding an algorithm, writing code for narrow well-defined tasks. All code written by AI was examined, refactored and cleanded up where necessary.

License

This project is licensed under the MIT License. See the LICENSE file for details.