README.md

February 4, 2026 · View on GitHub

ADHD Focus Mate

The AI companion that knows what you should be doing and gently reminds you when you get distracted.
Private. Open Source. AI-Powered.

Features • Installation • Why I built this • How it works • Privacy & Data • Troubleshooting

What is ADHD Focus Mate?

ADHD Focus Mate is a native macOS menu bar app that helps you stay in the "Flow State" by watching your screen. It is built purely in SwiftUI, making it super lightweight and resource-efficient (uses <1% CPU). It's also extremely cheap to run—optimized for token efficiency so it costs next to nothing (often <$1/month).

Unlike traditional timers that just count down, Focus Mate uses AI to understand what you're looking at. It quietly monitors your screen at your chosen interval. If it sees you working on your goal (e.g., Coding, Writing), it leaves you alone. But if it catches you doom-scrolling Reddit or watching YouTube when you should be working, it gives you a gentle, judgment-free nudge to get back on track.

Privacy-First: Screenshots are analyzed in-memory and instantly discarded. Your screen history is never saved to disk or trained on.

See it in Action

https://github.com/user-attachments/assets/ca3f26c7-788c-4bb5-af6d-0ce3462f3b3d

Features

🧘 Zen Timer: A beautiful, unobtrusive "Zen Pill" in your menu bar that shows your status at a glance.
👁️ It Knows What You're Doing: Uses smart AI to understand your screen, so it knows the difference between "working" and "wasting time".
🚫 Distraction Nudges: A gentle notification breaks your "doom-scrolling" trance before you lose hours.
🔍 Recognize & Fix Patterns: It spots your specific distraction triggers (like Twitter or Steam) and analyzes your patterns to help you understand and fix your focus habits.
📅 Session History: Review a detailed log of your focus sessions to track exactly what you worked on throughout the day.
💸 Wallet Friendly: Built with a Token Optimization Philosophy. We use smart image compression and efficient prompting to keep payload sizes tiny, ensuring costs stay extremely low (often <$1/month) even with all-day usage.

Installation

Requirements

macOS 14.0 (Sonoma) or later.
A Gemini API Key: You can get one completely free here—no credit card required. The free tier has generous limits that work great for this app.
- Why Paid? While the free tier works perfectly, we recommend enabling billing on your Google Cloud project to ensure Google does not train on your data.
  - Free $300 Credit: New Google Cloud accounts typically get $300 in free credits. This is enough to run this app privately for years without paying a cent.
  - Low Cost: Even without credits, the app usually costs <$1/month to run.
- Model Choice: We recommend using a lightweight, cost-efficient model like gemini-2.5-flash-lite. The classification task is simple enough that you don't need a more powerful (and expensive) model.

Install via Homebrew (Preferred)

Install via Homebrew to get autoupdates.

brew install --cask skainguyen1412/tap/adhd-focus-mate

Manual Install

You can also install manually:

Download the latest available zip from releases page
Unpack zip
Put unpacked ADHD Focus Mate.app into /Applications folder

Note

This app is signed and notarized by Apple, so you should not see any security warnings when opening it.

Build from Source

Clone the repo:

git clone https://github.com/skainguyen1412/adhd-focus-mate.git
cd adhd-focus-mate

Install Tuist:

curl -Ls https://install.tuist.io | bash

Generate Project:
```
tuist install
tuist generate
```
Run: Open ADHDFocusMate.xcworkspace, select the ADHDFocusMate scheme, and hit Cmd+R.

Why I built this

I built Focus Mate because whenever I sit down to code, I eventually drift.

One minute I'm debugging a function, and the next—without even realizing it—I'm scrolling X (Twitter) or watching TikToks. I lose track of time completely. 10 minutes turns into 45, and my flow is dead.

I thought it would be really cool to have an app that actually knows what I'm doing. Not just a dumb timer, but something smart enough to track my context and gently remind me if I lose focus.

So I built it. ADHD Focus Mate is that intelligent companion—it sees when you're working, notices when you drift, and helps you stay in the zone without being annoying.

Roadmap

We have big plans to make Focus Mate the ultimate productivity tool:

🔮 Local AI Support: We are working on supporting local LLM/VLM models (like Ollama or CoreML). This will allow the app to run 100% offline, be fully private, and completely free forever.
📊 Advanced Insights: Deeper analytics to help you understand your productivity flow.
⚡️ Shortcuts Integration: Control Focus Mate with macOS Shortcuts.

How it works

The app operates on a simple "Capture → Analyze → Feedback" loop designed to be lightweight and private.

Capture: At your chosen interval (1-5 minutes), the app takes a screenshot.
Analyze: The image is sent to the Gemini API (gemini-2.5-flash-lite by default) along with your personalized focus context.
Classify: The AI responds with a classification (e.g., label: slack, category: social_media).
Action:
- If Work: Increase your Focus Streak. 🎉
- If Slack: Send a nudge notification + enter "Cooldown Mode" (so it doesn't spam you).
Privacy: The screenshot is immediately deleted from memory. It rarely exists for more than 2 seconds.

Paid Tier (Recommended): If you enable billing on your Google Cloud project (even if you stay within free quotas), Google states they do not train on your data. This is the best way to ensure privacy.
Free Tier: If you use the completely free tier, Google may use anonymized data to improve their models.

Troubleshooting

"Permission Required" Loop

Sometimes macOS gets stuck.

Open System Settings → Privacy & Security → Screen Recording.
Remove ADHD Focus Mate (click -).
Restart the app and grant permission again.

API Connection Failed

Ensure you copied the full API key (starts with AIza...).
Check if your quota is exceeded on Google AI Studio.
If using Vertex AI, ensure your project is properly configured.

Notifications Not Working

Open System Settings → Notifications.
Find ADHD Focus Mate and ensure notifications are enabled.
Check that "Allow Notifications" is turned on.

Contributing

We welcome contributions!

Bug Reports: Open an issue.
Feature Requests: We love new ideas for visualization or AI prompts.
PRs: Please follow the SwiftLint rules and ensure tests pass (tuist test).

Acknowledgements

Dayflow: A really cool app with an awesome idea—automatically creating a timeline of your day. It was a huge inspiration for me to make this.

License

MIT License. See LICENSE for details.

Made with 🍃 (Hyperfocus)