Hard Pomodoro

Hard Pomodoro is a minimalist, productivity-focused Pomodoro timer designed to force you to take breaks by locking your system and optionally blocking all screens in fullscreen mode.

Unlike traditional timers, Hard Pomodoro doesn't just notify you—it enforces your breaks, making it ideal for deep work and avoiding burnout.

---

🔥 Features

• ✅ Set Pomodoro and break durations (default: 50/10 minutes).
• ✅ GUI with intuitive controls.
• ✅ Two blocking modes:
  • hard: locks the system and covers all screens with fullscreen black windows (kiosk mode).
  • light: locks the system only.
• ✅ Multi-monitor support.
• ✅ Cross-platform system lock (Windows, Linux, macOS).
• ✅ Break warning notification (45 seconds before lock).
• ✅ Python-based and open-source.

---

🚀 Requirements

• Python: Version 3.11 or higher is recommended.
• Tkinter: Required for the GUI. It is usually installed by default with Python, but verify its availability.

✅ Quick Verification

Check your Python version:

python --version

Verify Tkinter installation:

python -m tkinter

If a small window opens, Tkinter is installed correctly.

---

✅ Virtual Environment (Highly Recommended) It is highly recommended to create a virtual environment before installing dependencies to keep your setup isolated. Official Python documentation: venv

Example Commands:

Windows:

python -m venv .venv
.venv\\Scripts\\activate

macOS/Linux:

python3 -m venv .venv
source .venv/bin/activate

After activation, install dependencies:

pip install -r requirements.txt

📦 Installation

1. Clone the official repository:

git clone https://github.com/johnma96/hard-pomodoro.git
cd hard-pomodoro

2. Install dependencies:

pip install -r requirements.txt

---

🖥 Launch the GUI

python main.py

You’ll be prompted to enter:

• Pomodoro duration (in minutes)
• Break duration (in minutes)
• Mode: hard or light

---

⚙️ CLI Usage (Advanced)

You can also use the underlying functions from core.py directly:

from hard_pomodoro.core import countdown_console, lock_screen, kiosk_break

countdown_console(50 * 60, "Pomodoro")
lock_screen()
kiosk_break(10 * 60)

---

🛠 Build as Executable (.exe)

Want to use it as a native app on Windows?

1. Install PyInstaller:

pip install pyinstaller

2. Build the executable:

Traditional .exe:

pyinstaller --noconfirm --onefile --windowed main.py --name HardPomodoro --hidden-import=plyer.platforms.win.notification

Or add an icon to the .exe:

pyinstaller --noconfirm --onefile --windowed main.py --name HardPomodoro --hidden-import=plyer.platforms.win.notification --icon=assets/icon.ico

The .exe file will appear in the dist/ folder.

---

🧪 Development Setup

To install dev dependencies (e.g. for building the .exe):

pip install -r requirements-dev.txt

---

📁 Project Structure

hard_pomodoro/
├── .gitignore                # Git exclusions
├── LICENSE                   # MIT License
├── main.py                   # Entry point (launches GUI)
├── pyproject.toml            # Project metadata and dependencies
├── README.md                 # Project documentation
├── requirements.txt          # Runtime dependencies
├── requirements-dev.txt      # Dev-only dependencies (e.g. pyinstaller)
├── assets/
│   └── icon.ico              ← Here your personal icon.ico
└── hard_pomodoro/            # Package source code
    ├── __init__.py
    ├── core.py               # Core logic: timer, lock, kiosk
    └── gui.py                # GUI logic (Tkinter)

---

📜 License

This project is licensed under the MIT License.

---

🙌 Author

Developed by John Mario Montoya Zapata
Feel free to open issues or contribute via pull request.