Pomlock - A pomodoro application for Linux

A Linux utility that enforces regular breaks by temporarily blocking input devices. Perfect for developers, writers, and anyone who needs help stepping away from the keyboard.

Features

• Flexible Timer System: Supports multiple timer presets, including the classic Pomodoro, Ultradian Rhythm (90/20), and a 50/10 cycle. New presets can be defined in the configuration file, and a one-time custom timer can be passed as a command-line argument.
• Input Blocking: Blocks all input devices during breaks via direct kernel evdev grab. Falls back to Hyprland (hyprctl) then X11 (xinput) when a direct grab isn't possible.
• Customizable Overlay: A full-screen display during breaks with configurable font, colors, and opacity.
• Desktop Notifications: Get native desktop notifications when a break starts.
• Activity Tracking: Tag sessions with --activity (e.g., coding, writing) and list configured activities with --show-activities.
• Activity Logging: Keeps a simple log of work and break cycles at ~/.local/share/pomlock/pomlock.log.
• Safe Mode: Run the timer without input blocking using the --no-block-input flag.
• Smart Configuration: Settings are loaded in a logical order: Defaults < Config File < CLI Arguments. CLI flags always have the final say.

Installation

pipx

pipx install pomlock

Waybar Integration (Optional)

pomlock comes with a Waybar script that synchronizes automatically with your pomodoro sessions. You can find it at src/pomlock/waybar.py.

To use it, copy the script to your Waybar scripts directory (e.g., ~/.config/waybar/scripts/) and configure your Waybar config file.

Example Waybar Configuration:

"custom/pomodoro": {
    "exec": "/path/to/your/waybar.py",
    "interval": 1,
    "return-type": "json",
    "on-click": "/path/to/your/waybar.py left",
    "on-click-right": "/path/to/your/waybar.py right"
}

Replace /path/to/your/waybar.py with the actual path where you copied the script.

Usage

# Start with the default 'standard' preset (25min work, 5min break)
pomlock

# Use the 'ultradian' preset for a long deep-work session (90min work, 20min break)
pomlock --timer ultradian

# Use the 'fifty_ten' preset for a 50/10 work-break cycle.
pomlock --timer fifty_ten

# Set a custom timer: 45min work, 15min short break, 30min long break after 3 cycles
pomlock --timer "45 15 30 3"

# Tag the session with an activity name (logged and shown in the UI)
pomlock --activity coding

# List all configured activities and exit
pomlock --show-activities

# Set a custom overlay text color for the session
pomlock --overlay-color "lime"

# Run without blocking input devices
pomlock --no-block-input

Integrations

pomlock can be integrated with other tools like status bars (Waybar, Polybar, etc.) in two ways:

Polling

On startup, pomlock creates a state file at /tmp/pomlock.json. This file contains the current timer information, including the action (pomodoro, short_break, long_break), duration, and start time.

You can write a script to poll this JSON file every second to create a custom status bar component. The file is automatically deleted when pomlock exits.

Example State File Content:

{
    "action": "pomodoro",
    "time": 1,
    "start_time": 1756677567.9689746,
    "crr-cycle": 1,
    "total-cycles": 4,
    "crr-session": 1
}

Callback

For event-driven integrations, you can use the --callback flag to execute a script whenever a pomodoro or break begins. pomlock will pass a JSON string with the timer data as the last argument to your script.

pomlock --callback /path/to/your/script.sh

Your script will be executed silently in the background to avoid disrupting the main pomlock terminal UI.

Configuration

You can create a custom configuration file at ~/.config/pomlock/pomlock.conf to override the default settings. CLI arguments will always override settings from this file.

Here is an example configuration showing all available options:

# ~/.config/pomlock/pomlock.conf

[pomodoro]
# These values define the timer components when not using a preset.
# timer = 30 5 15 4
pomodoro = 30
short_break = 5
long_break = 15
cycles_before_long = 4
block_input = true

[overlay]
# Customize the appearance of the break screen.
font_size = 64
color = red
bg_color = white
opacity = 0.5
notify = false
# notify_message = Time for a break!

[presets]
# Define your own custom timer presets.
# Format: "WORK SHORT_BREAK LONG_BREAK CYCLES"
standard = 25 5 20 4
ultradian = 90 20 20 1
fifty_ten = 50 10 10 1

[activities]
# Comma-separated list of activity names available to --activity.
available = coding, writing, reading, other

Log File

Location: ~/.local/share/pomlock/pomlock.log

Example Log Output:

2023-10-27 10:00:00 - INFO - Pomodoro started (25 minutes).
2023-10-27 10:25:00 - INFO - Pomodoro completed (Duration: 25m) (Cycle: 1)
2023-10-27 10:25:00 - INFO - Short break started (Duration: 5m) (Cycle: 1)
2023-10-27 10:30:00 - INFO - Break completed (Cycle: 1)

Safety

• Automatic Restoration: Input devices are automatically re-enabled when the program exits cleanly or is interrupted (Ctrl+C).
• Non-Blocking Mode: Use --no-block-input for safe, non-blocking monitoring.
• Force Quit: If the application becomes unresponsive, you can force it to close and restore input by running:

  pkill -f pomlock