# 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**: Disables all input devices during break periods to ensure you step away.
- **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 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 `--enable-input-during-break` flag.
- **Smart Configuration**: Settings are loaded in a logical order: Defaults < Config File < CLI Arguments. CLI flags always have the final say.
## Installation
### pip
```bash
pip install pomlock
```
### uv
```bash
uv tool install pomlock
```
<!-- ### Arch Linux (AUR) -->
<!-- ```bash -->
<!-- yay -S pomlock -->
<!-- ``` -->
<!-- ```bash -->
<!-- paru -S pomlock -->
<!-- ``` -->
<!---->
<!-- ### Manual -->
<!---->
<!-- <!-- TODO: some ideas --> -->
<!-- options: -->
<!-- 1. curl command: -->
<!-- [uv package manager](https://github.com/astral-sh/uv?tab=readme-ov-file#installation) -->
<!-- ```bash -->
<!-- curl -LsSf https://astral.sh/uv/install.sh | sh -->
<!-- ``` -->
<!-- [yt-dlp](https://github.com/yt-dlp/yt-dlp/wiki/Installation#installing-the-release-binary) -->
<!-- ```bash -->
<!-- curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o ~/.local/bin/yt-dlp -->
<!-- chmod a+rx ~/.local/bin/yt-dlp # Make executable -->
<!-- ``` -->
<!---->
<!-- 2. pip -->
<!-- [uv](https://github.com/astral-sh/uv?tab=readme-ov-file#installation) -->
<!-- ```bash -->
<!-- # With pip. -->
<!-- pip install uv -->
<!-- ``` -->
<!-- [yt-dlp](https://github.com/yt-dlp/yt-dlp/wiki/Installation#with-pip) -->
<!-- ```bash -->
<!-- python3 -m pip install -U "yt-dlp[default]" -->
<!-- ``` -->
<!---->
<!-- 3. pacman -->
<!-- [yt-dlp](https://github.com/yt-dlp/yt-dlp/wiki/Installation#pacman) -->
<!-- ```bash -->
<!-- sudo pacman -Syu yt-dlp -->
<!-- ``` -->
## Usage
```bash
# 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"
# Set a custom overlay text color for the session
pomlock --overlay-color "lime"
# Run without blocking input devices
pomlock --enable-input-during-break
```
## 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:
```ini
# ~/.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
enable_input_during_break = false
[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
```
## Log File
**Location**: `~/.local/share/pomlock/pomlock.log`
**Example Log Output**:
```log
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 `--enable-input-during-break` for safe, non-blocking monitoring.
- **Force Quit**: If the application becomes unresponsive, you can force it to close and restore input by running:
```bash
pkill -f pomlock.py
```
Raw data
{
"_id": null,
"home_page": null,
"name": "pomlock",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "pomodoro, timer, productivity, focus, linux, cli, input-blocker, break-timer, time-management",
"author": "Luis Cadillo",
"author_email": "Luis Cadillo <luiscaf3r@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/29/f0/12710d332f5aa6744150be2c6cdffe4b0f6e2fd9b61d20a22b29436f2448/pomlock-1.2.1.tar.gz",
"platform": null,
"description": "# Pomlock - A pomodoro application for Linux\n\n\n\nA 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.\n\n## Features\n\n- **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.\n- **Input Blocking**: Disables all input devices during break periods to ensure you step away.\n- **Customizable Overlay**: A full-screen display during breaks with configurable font, colors, and opacity.\n- **Desktop Notifications**: Get native desktop notifications when a break starts.\n- **Activity Logging**: Keeps a simple log of work and break cycles at `~/.local/share/pomlock/pomlock.log`.\n- **Safe Mode**: Run the timer without input blocking using the `--enable-input-during-break` flag.\n- **Smart Configuration**: Settings are loaded in a logical order: Defaults < Config File < CLI Arguments. CLI flags always have the final say.\n\n\n## Installation\n\n### pip\n```bash\npip install pomlock\n```\n\n### uv\n```bash\nuv tool install pomlock\n```\n\n<!-- ### Arch Linux (AUR) -->\n<!-- ```bash -->\n<!-- yay -S pomlock -->\n<!-- ``` -->\n<!-- ```bash -->\n<!-- paru -S pomlock -->\n<!-- ``` -->\n<!---->\n<!-- ### Manual -->\n<!---->\n<!-- <!-- TODO: some ideas --> -->\n<!-- options: -->\n<!-- 1. curl command: -->\n<!-- [uv package manager](https://github.com/astral-sh/uv?tab=readme-ov-file#installation) -->\n<!-- ```bash -->\n<!-- curl -LsSf https://astral.sh/uv/install.sh | sh -->\n<!-- ``` -->\n<!-- [yt-dlp](https://github.com/yt-dlp/yt-dlp/wiki/Installation#installing-the-release-binary) -->\n<!-- ```bash -->\n<!-- curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o ~/.local/bin/yt-dlp -->\n<!-- chmod a+rx ~/.local/bin/yt-dlp # Make executable -->\n<!-- ``` -->\n<!---->\n<!-- 2. pip -->\n<!-- [uv](https://github.com/astral-sh/uv?tab=readme-ov-file#installation) -->\n<!-- ```bash -->\n<!-- # With pip. -->\n<!-- pip install uv -->\n<!-- ``` -->\n<!-- [yt-dlp](https://github.com/yt-dlp/yt-dlp/wiki/Installation#with-pip) -->\n<!-- ```bash -->\n<!-- python3 -m pip install -U \"yt-dlp[default]\" -->\n<!-- ``` -->\n<!---->\n<!-- 3. pacman -->\n<!-- [yt-dlp](https://github.com/yt-dlp/yt-dlp/wiki/Installation#pacman) -->\n<!-- ```bash -->\n<!-- sudo pacman -Syu yt-dlp -->\n<!-- ``` -->\n\n\n## Usage\n\n```bash\n# Start with the default 'standard' preset (25min work, 5min break)\npomlock\n\n# Use the 'ultradian' preset for a long deep-work session (90min work, 20min break)\npomlock --timer ultradian\n\n# Use the 'fifty_ten' preset for a 50/10 work-break cycle.\npomlock --timer fifty_ten\n\n# Set a custom timer: 45min work, 15min short break, 30min long break after 3 cycles\npomlock --timer \"45 15 30 3\"\n\n# Set a custom overlay text color for the session\npomlock --overlay-color \"lime\"\n\n# Run without blocking input devices\npomlock --enable-input-during-break\n```\n\n## Configuration\n\nYou 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.\n\nHere is an example configuration showing all available options:\n```ini\n# ~/.config/pomlock/pomlock.conf\n\n[pomodoro]\n# These values define the timer components when not using a preset.\n# timer = 30 5 15 4\npomodoro = 30\nshort_break = 5\nlong_break = 15\ncycles_before_long = 4\nenable_input_during_break = false\n\n[overlay]\n# Customize the appearance of the break screen.\nfont_size = 64\ncolor = red\nbg_color = white\nopacity = 0.5\nnotify = false\n# notify_message = Time for a break!\n\n[presets]\n# Define your own custom timer presets.\n# Format: \"WORK SHORT_BREAK LONG_BREAK CYCLES\"\nstandard = 25 5 20 4\nultradian = 90 20 20 1\nfifty_ten = 50 10 10 1\n```\n\n## Log File\n\n**Location**: `~/.local/share/pomlock/pomlock.log`\n\n**Example Log Output**:\n```log\n2023-10-27 10:00:00 - INFO - Pomodoro started (25 minutes).\n2023-10-27 10:25:00 - INFO - Pomodoro completed (Duration: 25m) (Cycle: 1)\n2023-10-27 10:25:00 - INFO - Short break started (Duration: 5m) (Cycle: 1)\n2023-10-27 10:30:00 - INFO - Break completed (Cycle: 1)\n```\n\n## Safety\n\n- **Automatic Restoration**: Input devices are automatically re-enabled when the program exits cleanly or is interrupted (Ctrl+C).\n- **Non-Blocking Mode**: Use `--enable-input-during-break` for safe, non-blocking monitoring.\n- **Force Quit**: If the application becomes unresponsive, you can force it to close and restore input by running:\n ```bash\n pkill -f pomlock.py\n ```\n",
"bugtrack_url": null,
"license": null,
"summary": "A Linux utility that enforces regular breaks by temporarily blocking input devices",
"version": "1.2.1",
"project_urls": {
"Issues": "https://github.com/luiisca/pomlock/issues",
"Repository": "https://github.com/luiisca/pomlock"
},
"split_keywords": [
"pomodoro",
" timer",
" productivity",
" focus",
" linux",
" cli",
" input-blocker",
" break-timer",
" time-management"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "93aa29e14d288ca26d141eb320ee5a97a269ab36c0d21fc47ffe30e0e7701814",
"md5": "e4fb3da512976a449f9e3d307d8eccda",
"sha256": "0f1c34dd90efb9fd2897f8045432ecad8742ea268b3b28e38d0a8b0014dbc2fc"
},
"downloads": -1,
"filename": "pomlock-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e4fb3da512976a449f9e3d307d8eccda",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 9861,
"upload_time": "2025-08-10T07:03:59",
"upload_time_iso_8601": "2025-08-10T07:03:59.329873Z",
"url": "https://files.pythonhosted.org/packages/93/aa/29e14d288ca26d141eb320ee5a97a269ab36c0d21fc47ffe30e0e7701814/pomlock-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "29f012710d332f5aa6744150be2c6cdffe4b0f6e2fd9b61d20a22b29436f2448",
"md5": "806b20bab702ec96d77a46463fdf057c",
"sha256": "f67182ff4abaee983fa0bbdf933060cc5af35ef5239f7fb197b8ade7b0ad602c"
},
"downloads": -1,
"filename": "pomlock-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "806b20bab702ec96d77a46463fdf057c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 8526,
"upload_time": "2025-08-10T07:04:00",
"upload_time_iso_8601": "2025-08-10T07:04:00.370660Z",
"url": "https://files.pythonhosted.org/packages/29/f0/12710d332f5aa6744150be2c6cdffe4b0f6e2fd9b61d20a22b29436f2448/pomlock-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-10 07:04:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "luiisca",
"github_project": "pomlock",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pomlock"
}
JSON
