# 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 `--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
```bash
pipx install pomlock
```
### Manual Installation (for Wayland users)
If you are on a Wayland system and intend to use `pomlock`'s input blocking features, you will need to manually copy the Polkit policy files. These files grant `pomlock` the necessary permissions to interact with input devices via `libinput` and `evtest`, which require `sudo` privileges.
1. **Copy Polkit Policy Files**:
```bash
sudo cp src/polkit-actions/*.policy /usr/share/polkit-1/actions/
```
This step is crucial for `pomlock` to be able to block input devices on Wayland.
2. **Install Dependencies**: Ensure you have `libinput` and `evtest` installed on your system. These are typically available through your distribution's package manager.
* For Debian/Ubuntu: `sudo apt install libinput-tools evtest`
* For Fedora: `sudo dnf install libinput-utils evtest`
* For Arch Linux: `sudo pacman -S libinput evtest`
3. **Install `pomlock` (Python package)**:
First, ensure you have `uv` installed:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Then, navigate to the `pomlock` project directory and install it in editable mode:
```bash
uv pip install -e .
```
This will install `pomlock` and all its Python dependencies.
4. **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**:
```json
"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"
}
```
Remember to replace `/path/to/your/waybar.py` with the actual path where you copied the script.
<!-- ### 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 --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:**
```json
{
"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.
```bash
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:
```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
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
```
## 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 `--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:
```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/7b/b7/1fd266a8f394d0558512b51325dcaf3dfb3dcfe2dd068d8996f1c62aca5b/pomlock-2.0.0.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 `--no-block-input` 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### pipx\n```bash\npipx install pomlock\n```\n\n### Manual Installation (for Wayland users)\n\nIf you are on a Wayland system and intend to use `pomlock`'s input blocking features, you will need to manually copy the Polkit policy files. These files grant `pomlock` the necessary permissions to interact with input devices via `libinput` and `evtest`, which require `sudo` privileges.\n\n1. **Copy Polkit Policy Files**:\n ```bash\n sudo cp src/polkit-actions/*.policy /usr/share/polkit-1/actions/\n ```\n This step is crucial for `pomlock` to be able to block input devices on Wayland.\n\n2. **Install Dependencies**: Ensure you have `libinput` and `evtest` installed on your system. These are typically available through your distribution's package manager.\n * For Debian/Ubuntu: `sudo apt install libinput-tools evtest`\n * For Fedora: `sudo dnf install libinput-utils evtest`\n * For Arch Linux: `sudo pacman -S libinput evtest`\n\n3. **Install `pomlock` (Python package)**:\n First, ensure you have `uv` installed:\n ```bash\n curl -LsSf https://astral.sh/uv/install.sh | sh\n ```\n Then, navigate to the `pomlock` project directory and install it in editable mode:\n ```bash\n uv pip install -e .\n ```\n This will install `pomlock` and all its Python dependencies.\n\n4. **Waybar Integration (Optional)**:\n `pomlock` comes with a Waybar script that synchronizes automatically with your pomodoro sessions. You can find it at `src/pomlock/waybar.py`.\n\n To use it, copy the script to your Waybar scripts directory (e.g., `~/.config/waybar/scripts/`) and configure your Waybar `config` file.\n\n **Example Waybar Configuration**:\n ```json\n \"custom/pomodoro\": {\n \"exec\": \"/path/to/your/waybar.py\",\n \"interval\": 1,\n \"return-type\": \"json\",\n \"on-click\": \"/path/to/your/waybar.py left\",\n \"on-click-right\": \"/path/to/your/waybar.py right\"\n }\n ```\n Remember to replace `/path/to/your/waybar.py` with the actual path where you copied the script.\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 --no-block-input\n```\n\n## Integrations\n\n`pomlock` can be integrated with other tools like status bars (Waybar, Polybar, etc.) in two ways:\n\n### Polling\n\nOn 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.\n\nYou 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.\n\n**Example State File Content:**\n```json\n{\n \"action\": \"pomodoro\",\n \"time\": 1,\n \"start_time\": 1756677567.9689746,\n \"crr-cycle\": 1,\n \"total-cycles\": 4,\n \"crr-session\": 1\n}\n```\n\n### Callback\n\nFor 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.\n\n```bash\npomlock --callback /path/to/your/script.sh\n```\n\nYour script will be executed silently in the background to avoid disrupting the main `pomlock` terminal UI.\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\nblock_input = true\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 `--no-block-input` 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": "2.0.0",
"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": "ec8ce7c154123c9e229024288bef37f5052242439c7626a33804bf46ab973b69",
"md5": "ef8115c5694516f6c85467716658f498",
"sha256": "58b5210483f05b194272c4bf51de71d2e74fb3535521250aa96f39b66c6a75fa"
},
"downloads": -1,
"filename": "pomlock-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ef8115c5694516f6c85467716658f498",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 19613,
"upload_time": "2025-10-17T17:34:48",
"upload_time_iso_8601": "2025-10-17T17:34:48.982508Z",
"url": "https://files.pythonhosted.org/packages/ec/8c/e7c154123c9e229024288bef37f5052242439c7626a33804bf46ab973b69/pomlock-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7bb71fd266a8f394d0558512b51325dcaf3dfb3dcfe2dd068d8996f1c62aca5b",
"md5": "22becc395d692149aed4bf8a51dfb071",
"sha256": "e9a457f6f9c410f4f1d8c410de8110697ac53b3163f35571e6536ad4ec76cee7"
},
"downloads": -1,
"filename": "pomlock-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "22becc395d692149aed4bf8a51dfb071",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 16280,
"upload_time": "2025-10-17T17:34:50",
"upload_time_iso_8601": "2025-10-17T17:34:50.332408Z",
"url": "https://files.pythonhosted.org/packages/7b/b7/1fd266a8f394d0558512b51325dcaf3dfb3dcfe2dd068d8996f1c62aca5b/pomlock-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-17 17:34:50",
"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
