programmingHabits

Developed with:

Developed for:

---

Description

programmingHabits is a native Linux productivity tool designed to integrate the Pomodoro technique into your desktop environment. Unlike simple timers, it enforces healthy habits by taking over your screen during breaks, ensuring you actually stop working to stretch, hydrate, and rest your eyes. It is built to look and feel like a native part of your Desktop Environment.

Inspiration

As a programmer, I often found myself getting so engrossed in coding that I would forget to take breaks, stay hydrated, or even move around. This led to fatigue and a decline in productivity over time. Realising the importance of maintaining good habits and overall health, I decided to create a project that would help programmers like me stay healthy and productive. Thus, programmingHabits was born, a tool to remind us to take care of ourselves while we code.

Features

• Smart Pomodoro Timer: Customizable work and break intervals stored permanently.
• Enforced Breaks: A full-screen, semi-transparent overlay blocks the screen, gently forcing you to step away.
• Native Theme Integration: Automatically inherits your system GTK theme — works on GNOME, KDE, XFCE, MATE, Cinnamon, and more.
• Smart Media Control: Automatically pauses Spotify, YouTube, or any MPRIS2-compatible media player when a break starts (via D-Bus).
• Health & Wisdom: Displays curated health tips and programming wisdom during breaks.
• System Tray Indicator: Manage the timer, access settings, or quit the app directly from your system tray.
• Audio Alerts: Gentle chimes to signal the start of breaks (supports PulseAudio and PipeWire).
• Tiny Package: ~50 KB installed size — uses your system's existing GTK and Python libraries.

Installation

Option 1 (Recommended): Install via APT (Ubuntu/Debian/Mint)

1. Add the Repository Key:

   curl -fsSL https://prathampt.github.io/programmingHabits/KEY.gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/programminghabits.gpg

2. Add the Repository:

   echo "deb [signed-by=/etc/apt/trusted.gpg.d/programminghabits.gpg] https://prathampt.github.io/programmingHabits/ /" | sudo tee /etc/apt/sources.list.d/programminghabits.list

3. Install:

   sudo apt update
   sudo apt install programminghabits

Option 2: Build from Source

1. Clone the Repository:

   git clone https://github.com/prathampt/programmingHabits
   cd programmingHabits

2. Install Dependencies:

   sudo apt install python3-gi gir1.2-gtk-3.0 gir1.2-ayatanaappindicator3-0.1

3. Run in Dev Mode:

   python3 -m programminghabits.main

4. Build .deb Package:

   sudo apt install dpkg-dev debhelper
   dpkg-buildpackage -us -uc -b
   sudo dpkg -i ../programminghabits_*.deb

Architecture & Configuration

Directory Structure

programminghabits/
├── main.py         # Entry point. System tray indicator, timer state machine.
├── overlay.py      # Full-screen break overlay with media pausing.
├── settings.py     # Settings dialog (Timer and Quotes tabs).
├── config.py       # JSON settings management (~/.config/).
└── assets/         # Icons and sound files.
debian/             # Standard Debian packaging.
bin/                # Launcher script.
data/               # .desktop file for application menus.
Makefile            # Install/uninstall targets.

Configuration

The settings are stored in JSON format at: ~/.config/programminghabits/config.json

You can edit this file manually or use the Settings GUI via the System Tray indicator to:

• Enable/Disable the timer.
• Change Work/Break duration.
• Add your own custom motivational quotes.

Technologies Used

• Python 3: The core logic language.
• GTK 3 (GObject Introspection): Native GUI toolkit — pre-installed on virtually all Linux desktops.
• AyatanaAppIndicator3: Cross-DE system tray support (GNOME, KDE, XFCE, MATE, Cinnamon).
• D-Bus (GDBus): MPRIS2 media player control — no extra dependencies.
• Standard Debian Packaging: Native dpkg-buildpackage for clean, tiny packages.

Contribution

Feel free to fork this repository and submit pull requests. Your contributions are welcome!

Contributing Guidelines

1. Fork the Repository: Start by forking the project repository to your GitHub account.
2. Clone Locally: Clone the forked repository to your local machine using a Git client.
3. Create a New Branch: Always work on a new branch, giving it a descriptive name.

   git checkout -b feature/amazing-feature

4. Make Your Changes: Develop and test your changes locally.
5. Commit Your Changes: Commit with a clear message describing your updates.

   git commit -m 'Implemented amazing feature.'

6. Push to GitHub: Push the changes to your forked repository.

   git push origin feature/amazing-feature

7. Submit a Pull Request: Create a PR against the original project repository. Clearly describe the changes and their motivations.

License

This project is licensed under the GNU GENERAL PUBLIC LICENSE Version 3 - see the LICENSE file for details.

Fork and Star

Don't forget to fork the repository and give a star if you find it useful! Happy Coding & Stay Healthy.