FocusGuard (Focus-OS)

FocusGuard is a local-first desktop productivity app built with Python and PyQt5. It helps you run focused work sessions, monitor distractions, track scores and streaks, view analytics, and use break-time recovery tools.

Features

• Focus session timer with start, pause, resume, and stop controls
• Distraction detection with blocked app handling and idle tracking
• Points, focus score, streak, and daily metrics dashboard
• Analytics charts for score trends and activity mix
• History timeline and summary reports
• Multi-profile settings with local preferences
• Local login and account creation flow
• Focus music player (presets plus offline tracks)
• Break Lab with breathing routines, prompts, and mini game

Tech Stack

• Python 3.11+
• PyQt5 for desktop UI
• SQLite for local persistence
• psutil for process monitoring
• matplotlib for charts
• plyer for desktop notifications

Project Structure

Focus-OS/
	focusguard/
		core/       # business logic and services
		db/         # database manager and repositories
		ui/         # PyQt pages and widgets
		tests/      # unit and integration tests
		main.py     # app entry point
	requirements.txt
	README.md

Setup

1. Create and activate a virtual environment.

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1

2. Install dependencies.

pip install -r requirements.txt

Run the App

python -m focusguard.main

On first launch, create a local account in the login dialog.

Run Tests

python -m unittest discover -s focusguard/tests -p "test_*.py"

Data and Logs

• SQLite database file: focusguard.db (created automatically)
• Runtime log file: focusguard.log

All data is stored locally on your machine.

Troubleshooting

• App does not start:

  • Confirm virtual environment is active.
  • Reinstall dependencies from requirements.txt.
  • Check focusguard.log for traceback details.

• Windows script execution blocked (PowerShell):

  • Run PowerShell as current user with script support:
  • Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

• Notification or audio features unavailable:

  • Some environments may not expose desktop notification or multimedia backends.
  • Core focus tracking and UI features still run.

Notes

• FocusGuard is local-first by design. No cloud backend is required.
• Current implementation targets desktop usage, especially on Windows.