🎯 Focus Buddy

Your friendly desktop companion that helps you stay focused — and calls you out when you don't!

Focus Buddy is a free, open-source Windows app that lives in your system tray as a cute animated character. It watches your active window, runs Pomodoro-style focus sessions, calls out distractions, and tracks your focus statistics — all locally, with no accounts and no data leaving your machine.

✨ Features

• 🎭 Animated Character — A little blob buddy that reacts to your focus state: happy when you're working, angry when you get caught slacking, celebrating when a session completes. It shrinks into the corner and stays out of your way.
• 👁️ Active Window Monitoring — Detects what you're actually working on in real time.
• 🚨 Distraction Detection — Configurable list of distracting apps, window titles, and websites; the character calls you out with a speech bubble when it catches you.
• ⏱️ Focus Timer — Pomodoro-style focus sessions (1–180 min) with a live countdown on the character, breaks, and a grace period before alerts.
• 📊 Focus Statistics — Track focus time, distractions, and scores per day and per week, with a weekly bar chart, streaks, session history, and a read-only history table.
• 📈 Daily Goal Ring — Set a daily focus-minute goal; the character shows a small progress ring that turns green when you hit it.
• 🔔 System Tray — The tray icon shows the character tinted by your state (green focused, red distracted, gold celebrating, gray paused) with quick controls.
• 💬 Speech Bubbles — Messages float in their own bubble above the character — never overlapping it.
• ⚙️ Customizable — Add your own distractions, preset categories, timers, sounds, dark mode, and more.
• 🚀 Launch at Startup (new) — Optionally start quietly with Windows so the buddy is ready when you are.
• 🎵 Sound Effects — Subtle audio cues with volume control (toggleable).
• 📦 Standalone .exe — Single file, no installation, no console window, works on any Windows 10/11 machine.

🚀 Quick Start

Download

Grab the latest FocusBuddy.exe from the Releases page. Double-click and it just works — no installation, no Python, no dependencies.

Run from Source

git clone https://github.com/GAWD09/focus-buddy.git
cd focus-buddy

pip install -r requirements.txt
python main.py

💡 Running from source opens a console window alongside the app. The packaged FocusBuddy.exe is built --windowed and runs with no console window.

Build the Executable

pip install pyinstaller
python build.py            # builds dist/FocusBuddy.exe (console-less, icon embedded)
python build.py --portable # also creates dist/FocusBuddy-Portable.zip

🎮 How It Works

1. Start Focus Buddy — the character appears near your taskbar, bottom-right.
2. Work normally — Focus Buddy watches your active window.
3. Get called out — open YouTube, Twitter, or any distraction and the character reacts.
4. Start a focus session — double-click the character, or use the tray/character menus.
5. Track your progress — open Statistics to see your daily score, weekly chart, streaks, and history.

Controls

Action	How
Start / end focus session	Double-click the character, Ctrl+Space, or tray/character menu
Pause / resume monitoring	Character or tray menu, or Ctrl+P
Quick controls	Right-click the character (session, pause, stats, settings, quit)
Show / hide character	Ctrl+H
Quit	Tray menu → Quit, or Ctrl+Q
Move the character	Drag it anywhere on screen

Character Moods

State	What it means
😊 Happy / Focused	You're working productively — squinty happy eyes
😠 Angry	Distraction detected!
🎉 Celebrating	Focus session complete!
💤 Sleepy	Monitoring is paused
🤔 Thinking / Idle	Just chilling

⚙️ Configuration

Open Settings from the tray or character menu:

• 🚫 Distractions — add/remove keywords and apps; preset categories (Social Media, Gaming, Video, Shopping).
• ⏱ Timer — focus session duration (1–180 min), break duration, grace period before alerts.
• 🎨 Appearance — dark mode, show/hide the character, lock its position, sounds + volume, desktop notifications, daily focus goal.
• ⚡ Advanced — monitoring check interval, launch at Windows startup, and clearing all statistics.

🔑 Keyboard Shortcuts

Shortcut	Action
Ctrl+Space	Toggle focus session
Ctrl+P	Pause / resume monitoring
Ctrl+H	Show / hide the character
Ctrl+Q	Quit Focus Buddy

🔒 Data & Privacy

• Everything is stored locally in %APPDATA%\FocusBuddy\ — no cloud, no accounts, no telemetry.
• Focus sessions, statistics, and settings live in plain JSON you can inspect or back up.
• A detailed log (focus_buddy.log) records sessions, distractions, and any errors — handy for debugging.

🛠️ For Developers

Project Structure

focus-buddy/
├── main.py                    # Entry point
├── build.py                   # PyInstaller build script
├── make_icon.py               # Regenerates assets/icon.ico from the character
├── requirements.txt           # Dependencies
├── LICENSE                    # MIT License
└── focus_buddy/               # Main package
    ├── __init__.py            # Package info & version
    ├── app.py                 # Application controller, settings, shortcuts
    ├── autostart.py           # Windows "launch at startup" registry integration
    ├── window_monitor.py      # Active-window tracking
    ├── focus_engine.py        # Distraction detection, sessions, stats, streaks
    ├── character_renderer.py  # Character drawing with QPainter
    ├── character_widget.py    # Floating character + speech bubble windows
    ├── system_tray.py         # Tray icon with per-state character tinting
    ├── settings_dialog.py     # Settings UI
    ├── stats_dialog.py        # Statistics UI (score ring, weekly chart, history)
    └── audio_manager.py       # Sound effects

Dependencies

• PyQt6 — GUI framework
• pywin32 — Windows API access (active-window detection)
• psutil — Process management

Running the Tests

python tests/test_focus_engine.py  # engine logic: distractions, sessions, stats, streaks
python tests/test_integration.py   # full app: character, dialogs, sessions, tray, shortcuts, weekly chart
python tests/test_autostart.py     # registry auto-start integration (uses a throwaway key)

All suites run against isolated temporary data and never touch your real statistics.

Regenerating the App Icon

The icon (assets/icon.ico) is rendered from the actual character and embedded into the executable:

python make_icon.py   # regenerates assets/icon.ico (256..16 px)
python build.py       # rebuilds dist/FocusBuddy.exe with the icon embedded

📝 License

Released under the MIT License. Free to use, modify, and distribute — including commercially.

🙏 Contributing

Contributions are welcome! Feel free to:

• Report a bug
• Suggest a feature
• Submit pull requests
• Improve documentation

Please open an issue before starting large changes so we can discuss them.

💬 About

Focus Buddy was created to make staying focused feel a little more playful. It's free, open source, and respects your privacy — your data never leaves your computer.

---

Made with ❤️ for productive people everywhere.