Forty-Five Break 🧘

A lightweight background service for Ubuntu/Debian Linux that reminds you to take breaks after 45 minutes of continuous computer use. Help maintain your health and productivity with regular break reminders!

Features

• ⏱️ Smart Usage Tracking: Monitors continuous active usage time
• 🔒 Idle Detection: Automatically pauses when screen is locked or system is idle
• 🔔 Desktop Notifications: Uses native Ubuntu notifications
• ⚙️ Highly Configurable: Customize break intervals, idle thresholds, and notification messages
• 🎬 Custom Rules: Skip notifications during specific activities (movies, games, etc.)
• 🪶 Minimal Resource Usage: Designed to run in the background with minimal CPU and memory impact
• 🚀 Auto-start: Runs automatically at system startup via systemd

How It Works

1. The service starts automatically when you log in
2. It monitors your active usage time (excluding idle/lock periods)
3. After 45 minutes (configurable) of continuous active use, you get a notification
4. Timer resets after the notification or when you lock your screen
5. Process repeats to help you maintain healthy break habits

Requirements

• Ubuntu, Debian, or other Debian-based Linux distribution
• Python 3.6 or higher
• X11 display server
• xprintidle - for idle time detection
• libnotify-bin - for desktop notifications

Installation

Quick Install

1. Clone or download this repository:

cd ~/Documents
git clone <repository-url> forty_five_break
# Or if you already have the files:
cd ~/Documents/forty_five_break

2. Run the installation script:

chmod +x install.sh
./install.sh

The installer will:

• Check for required dependencies and install them if missing
• Set up configuration files
• Install the systemd service
• Optionally start and enable the service

Manual Installation

If you prefer to install manually:

1. Install dependencies:

sudo apt-get update
sudo apt-get install -y python3 xprintidle libnotify-bin

2. Create configuration directory:

mkdir -p ~/.config/forty_five_break
cp config.json.example ~/.config/forty_five_break/config.json

3. Install systemd service:

mkdir -p ~/.config/systemd/user
cp forty-five-break.service ~/.config/systemd/user/
systemctl --user daemon-reload

4. Make script executable:

chmod +x forty_five_break.py

5. Start and enable the service:

systemctl --user enable forty-five-break.service
systemctl --user start forty-five-break.service

Configuration

The configuration file is located at ~/.config/forty_five_break/config.json.

Configuration Options

{
    "break_interval_minutes": 45,
    "idle_threshold_seconds": 300,
    "check_interval_seconds": 10,
    "notification_title": "Time for a Break! 🧘",
    "notification_message": "You've been working for 45 minutes. Take a 5-minute break!",
    "notification_urgency": "normal",
    "custom_rules": {
        "enabled": false,
        "process_blacklist": ["vlc", "mpv", "firefox"]
    }
}

Options Explained:

• break_interval_minutes: Time of continuous usage before notification (default: 45)
• idle_threshold_seconds: Seconds of inactivity before considering user idle (default: 300)
• check_interval_seconds: How often to check usage status (default: 10)
• notification_title: Title of the break notification
• notification_message: Message shown in the notification
• notification_urgency: Notification urgency level (low, normal, critical)
• custom_rules.enabled: Enable custom rule processing
• custom_rules.process_blacklist: List of process names that will skip notifications when running

Customizing for Movies/Games

To skip notifications when watching movies or playing games:

1. Edit your config file:

nano ~/.config/forty_five_break/config.json

2. Enable custom rules and add process names:

{
    ...
    "custom_rules": {
        "enabled": true,
        "process_blacklist": [
            "vlc",
            "mpv",
            "totem",
            "firefox",
            "chromium",
            "steam",
            "minecraft"
        ]
    }
}

3. Restart the service:

systemctl --user restart forty-five-break.service

Usage

Managing the Service

Start the service:

systemctl --user start forty-five-break.service

Stop the service:

systemctl --user stop forty-five-break.service

Restart the service:

systemctl --user restart forty-five-break.service

Check service status:

systemctl --user status forty-five-break.service

Enable auto-start at boot:

systemctl --user enable forty-five-break.service

Disable auto-start:

systemctl --user disable forty-five-break.service

Viewing Logs

View systemd logs:

journalctl --user -u forty-five-break.service -f

View application logs:

tail -f ~/.local/share/forty_five_break/monitor.log

Testing

To test if the service is working:

1. Start the service
2. Modify the config to use a shorter interval (e.g., 1 minute):

{
    "break_interval_minutes": 1,
    ...
}

3. Restart the service
4. Use your computer actively for 1 minute
5. You should see a notification
6. Change the config back to your preferred interval

Troubleshooting

Service won't start

• Check if Python 3 is installed: python3 --version
• Verify the script path in the service file matches your installation
• Check logs: journalctl --user -u forty-five-break.service -e

Notifications not appearing

• Ensure notify-send is installed: which notify-send
• Test notification manually: notify-send "Test" "This is a test"
• Check if DISPLAY and DBUS_SESSION_BUS_ADDRESS are set correctly

Idle detection not working

• Install xprintidle: sudo apt-get install xprintidle
• Test it: xprintidle (should show milliseconds since last input)

Service stops when logging out

• Enable lingering: loginctl enable-linger $USER

Uninstallation

To remove Forty-Five Break:

# Stop and disable the service
systemctl --user stop forty-five-break.service
systemctl --user disable forty-five-break.service

# Remove service file
rm ~/.config/systemd/user/forty-five-break.service
systemctl --user daemon-reload

# Remove config and logs (optional)
rm -rf ~/.config/forty_five_break
rm -rf ~/.local/share/forty_five_break

# Remove the project directory
rm -rf ~/Documents/forty_five_break

Contributing

Feel free to submit issues, fork the repository, and create pull requests for any improvements.

License

This project is open source and available under the MIT License.

Health Benefits of Regular Breaks

Taking regular breaks can:

• Reduce eye strain and prevent computer vision syndrome
• Decrease risk of repetitive strain injuries
• Improve focus and productivity
• Reduce stress and mental fatigue
• Promote better posture and physical health

Remember: Your health is more important than any deadline! 💚

FAQ

Q: Can I change the break interval?
A: Yes! Edit ~/.config/forty_five_break/config.json and change break_interval_minutes.

Q: Will it drain my battery?
A: No. The service is designed with minimal resource usage (CPU limited to 5%, memory capped at 50MB).

Q: What happens if I lock my screen?
A: The timer pauses automatically and resets when you lock your screen or become idle.

Q: Can I use this on non-Ubuntu Linux?
A: Yes, any Debian-based distribution should work. Other distros may work with minor adjustments.

Q: Does it work on Wayland?
A: This version is designed for X11. Wayland support may require modifications to the idle detection code.

---

Made with ❤️ for healthier computing habits