A buddy that helps you before procrastination gets you.

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady

What I Built

SlothGuard is an ambient local agent that quietly watches your screen and only speaks up when you appear stuck.
Most AI tools force you to break focus: select text, switch windows, write a prompt, and wait.
SlothGuard flips that. It runs in the background, takes low-resolution screenshots every few seconds, and detects when the screen has barely changed for a while (you’re staring at the same error, the same docs, or the same failing test). When that happens, it asks a local open-weight model for one short, calm tip and speaks it through local text-to-speech. Then it goes silent again.
It exists so developers (especially the ones coding late at night) can stay a little lazier. You don’t have to notice you’re stuck. You don’t have to decide to ask for help. The agent notices the stagnation and offers a gentle nudge only when it might actually be useful.

Demo

 https://github.com/tan-byte/slothguard

How I Built It

SlothGuard was built entirely around local, open-source AI. Rather than utilizing a closed API, every component was picked with privacy, offline capability, and customizability in mind.

Tech Stack

Component	Tool(s) Used	Purpose
Screen Capture	mss + Pillow	Fast, cross-platform, and low-resolution captures to minimize CPU usage.
Stagnation Detection	scikit-image (SSIM)	Compares perceptual similarity between grayscale, downscaled frames to detect when the screen has stayed nearly identical.
Local Inference	Ollama with moondream (preferred) or gemma2:2b	Generates a short, context-aware tip based off of the "stuck" signal. Vision capable models can utilize a cropped screenshot for better context.
Text-to-Speech	Piper TTS (en_US-lessac-medium)	Completely offline, neural TTS to audibly deliver the tip.
On-Screen Overlay	tkinter, ctypes, and Windows MessageBox fallbacks	A non-blocking, always-on-top popup to display the tip alongside audio for better visibility.
Orchestration	Python 3.10+, PyYAML, NumPy, Requests	Config loading, timing, cooldowns, and API calls to the local Ollama instance.

Architecture & Implementation Details

• Heuristic First: The detection logic is entirely local. SSIM is ran against downscaled, grayscale frames, only triggering an intervention if similarity is above the threshold for a configurable amount of time (~90 seconds by default).
• Model-Centric Tips: The heuristic only answers "Has this screen changed?". The open-weight model is responsible for answering "What should I say?". A constrained system prompt is fed to Ollama alongside an optional screenshot, forcing it to output one short, calm, and non-judgemental tip.
• Non-Blocking Design: Model generation, TTS, and overlays all run asynchronously or in their own processes, allowing the capture loop to resume without stalling.
• Resilient Fallbacks: If Piper isn't installed, it will gracefully print to console. If the overlay fails to initialize, it will fall back to a system message box or a highly visible console output, ensuring the tip is always delivered.
• Fully Configurable: All timings, thresholds, models, and cooldown ranges are exposed through config.yaml, allowing for easy tuning between "real use" and "demo" modes.
• Cooldown System: After each intervention, a randomized cooldown (5-8 minutes by default) is applied to prevent nagging, embodying the "only when useful" philosophy.

The open-weight model isn't an optional add on for this project, it's the core. Without it, SlothGuard would only be a timer playing a static message. With it, a generic "stuck" signal is transformed into a contextually relevant nudge.

Why Does Open Innovation Matter?

A closed API version of SlothGuard would require sending screenshots containing my actual code, stack traces, terminal output, and debugging sessions to a third-party server. For something designed to run all day in the background, this was a non-negotiable privacy concern.

Utilizing open-weight models locally allows for the following benefits:

• True Privacy: All data is processed on-device. Screenshots, prompts, and tips never leave the machine.
• Offline Reliability: It works anywhere. Trains, cafes with spotty Wi-Fi, or late nights with flaky internet are all a non-issue.
• Zero Marginal Cost: Once the model is pulled, SlothGuard can run for hours on end with no tokens, rate limits, or API fees to worry about.
• Freedom to Tinker: Anyone can swap models, iterate on the system prompt, tweak detection thresholds, or extend functionality without permission, paywalls, or vendor lock-in.

This level of autonomy, privacy, and flexibility is only possible due to the open-weight ecosystem and the tools that allow for local inference.

The Lazy Payoff

The value of SlothGuard isn't measured by saving minutes on a singular task, it's measured by removing the miniscule bits of friction that add up over the course of a day.

Traditionally, to get help when stuck, you have to go through a loop of: noticing you're stuck, deciding it's worth breaking flow for, switching contexts to ask an AI, formulating a prompt, and returning to your work.

SlothGuard cuts all of these steps out. By the time your brain registers that you've been circling the same bug for far too long, there's already a gentle, local tip being spoken to you. It's not about automating the solution, it's about automating the moment of asking for help. Less self-monitoring, less activation energy, and just a tiny nudge exactly when it's needed. That is the lazy payoff.