Focus Guardian

Inspiration

Every focus app we tried does the same thing: logs that you got distracted, throws a chart at you, done. The tab is still open, 20 minutes are gone, and the "analytics" show up after the damage is already done.

We wanted something that actually acts. Closes the tab. Kills the distraction. Coaches you back on track like a decent study partner would.

What it does

You tell it your goal: /start "build demo" 60. From there it watches every Chrome tab and running process, judges each one against your goal, and takes action — warns, closes the tab, or kills the app depending on mode (chill, normal, hardcore).

Every 10 minutes an AI coach checks in with drift patterns. At /stop, it scans your open editors, finds the git repos you were working in, runs git log and git diff, and gives you a per-project report: what you shipped, scope drift, a draft commit message. Next session, your tabs come back automatically.

How we built it

Python 3.11, Rich for the terminal UI, prompt_toolkit for slash commands, Playwright + raw CDP for Chrome control, Gemini 2.5 Flash via Vertex AI, psutil for process scanning, SQLite for persistence.

The loop is four layers: Detector → Policy → AI Judge → Tools. Every 2 seconds we list tabs, apply rules, ask the AI only for ambiguous cases, then act. Decisions are cached per URL so the same tab isn't re-classified every tick.

For the dev review: we scan editor processes, pull each one's cwd + cmdline path args, walk up to find a .git, then run git commands per repo. Gemini turns that into a short markdown report.

Challenges

Chrome 107+ blocks /json/new for DNS-rebinding protection — our tab restore silently failed. We ended up passing saved URLs as positional args to chrome.exe on spawn, skipping CDP entirely.

Playwright hangs when new tabs open mid-session in attach mode. We rewrote attach mode to hit CDP HTTP directly with urllib — non-blocking, no hangs.

Vertex AI quotas (429 RESOURCE_EXHAUSTED) hit us a lot because coach + judge + review all share one bucket. Added a 3-strike circuit breaker so the agent falls back to rules-only when AI dies.

Twenty parallel feature branches and orchestrator.py was the hot spot — everyone was editing init fields. Lots of manual conflict resolution, resolved by keeping both features when we could.

Tuning the judge was the hardest part. Too strict and it closes Stack Overflow pages you actually need; too loose and it ignores obvious drift. The rules-first / AI-second split came from this.

What we learned

Agents that act feel completely different from tools that observe. The loudest feedback during testing was "it actually closed the tab" — not the UI, not the stats.

Rules-first + AI-second is the right pattern when you care about cost, latency, and survival under rate limits. Cheap rules do the heavy lifting, AI handles the grey area.

Git is a surprisingly good data source for AI. A timestamp and git log --since is enough to write a review that feels specific.

A terminal UI can compete with a GUI when the workflow is keyboard-driven.

What's next

VS Code / JetBrains extension with inline focus signals and resume-here jump-to-file
Cross-session stuck-pattern detection (browsing history + git diffs together)
Calendar integration to auto-schedule focus blocks around meetings
Team mode with shared streaks and goals
Mobile companion that silences phone notifications during sessions