An AI agent that watches your local weather and nudges you like a friend — to walk, catch a sunset, or just open a window.
📺 Demo video coming soon. Star the repo to get notified!
Think of an agent like a recipe — a few simple ingredients working together:
| Ingredient | What It Does | In BreezyBuddy |
|---|---|---|
| 👀 Eyes | Observes the world | Open-Meteo Weather API |
| 🧠 Brain | Thinks and reasons | LLM via LiteLLM (Groq, OpenAI, Claude, Gemini, Ollama) |
| 📝 Memory | Remembers preferences | JSON file (user_preferences.json) |
| ⚙️ Decision Loop | Think → Act → Observe → Decide | ReAct agent loop |
| 📲 Voice | Takes action | Browser notifications + WhatsApp-style chat |
Most AI apps are just chatbots — you type, it replies. An agent is different. It observes, decides on its own, and reaches out to YOU. BreezyBuddy watches the weather and nudges you when conditions are right — like a friend who texts you "Dei, sunset is gorgeous, come outside."
- 🌤️ Weather-based lifestyle nudges (walk, sunset, fresh air, photography, window opening)
- 💬 WhatsApp-style chat UI
- 🔕 Background mode — set it and forget it, just get notifications (like Zomato)
- 🎭 6 personality modes (friendly friend, sarcastic friend, strict amma, gym bro, therapist, motivational mentor)
- 🌍 4 languages (English, Tamil, Tanglish, Mixed)
- 🤖 6 LLM providers (OpenAI, Groq, Gemini, Claude, Ollama, LM Studio)
- 🔄 ReAct agent loop with tool calls
- 🛡️ Safety guardrails (extreme weather blocking, emotional awareness, prompt injection defense)
- 💰 100% free — Open-Meteo (no API key) + Groq free tier
- 🏠 Runs locally, privacy-first
- 📱 Mobile-friendly responsive design
git clone https://github.com/sasilab/BreezyBuddy.git
cd BreezyBuddy# Linux/macOS
bash scripts/run_local.sh
# Windows PowerShell
.\scripts\run_local.ps1Or manually:
uv venv
source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
uv pip install -e .
cd backend && uvicorn main:app --reload --port 8000Prefer pip?
python -m venv .venv && source .venv/bin/activate && pip install -e .
Open http://localhost:8000 → click ⚙️ Settings → add your LLM API key.
🆓 Free option: Get a free key at console.groq.com → API Keys → Create 🏠 Local option: Install Ollama, select Ollama as provider, no key needed
Set your location and start chatting — or enable Background Mode and let BreezyBuddy nudge you automatically.
| Personality | Vibe | Example Nudge |
|---|---|---|
| 😊 Friendly Friend | Warm, supportive | "Hey! Weather's gorgeous, wanna go for a walk? 🌤️" |
| 😏 Sarcastic Friend | Lovingly roasts you | "Bro, you've been inside all day. The sun still exists." |
| 👩 Strict Amma | Tamil mom energy | "Whole day phone la iruka. Poi veliya. Now." |
| 💪 Gym Bro | Everything is gains | "Perfect outdoor workout weather. No excuses. Let's GO." |
| 🧘 Therapist | Gentle, mindful | "The weather is calm right now. A short walk might help." |
| 🌟 Motivational Mentor | Deep, inspiring | "Small steps. The breeze is calling. 10 minutes resets everything." |
flowchart TD
A[Weather API] -->|fetches conditions| B[Agent Decision Engine]
C[User Preferences JSON] -->|loads memory| B
D[Time of Day] -->|context| B
B -->|Safety Gate| E{Extreme Weather?}
E -->|Yes| F[⚠️ Hardcoded Safety Alert]
E -->|No| G[ReAct Loop]
G -->|Think| H[LLM reasons about conditions]
H -->|Act| I[Calls tools: weather, forecast, sun times]
I -->|Observe| J[Gets tool results]
J -->|Decide| K{Nudge the user?}
K -->|Yes| L[💬 Chat Message + 🔔 Notification]
K -->|No / SKIP| M[Wait for next interval]
The agent doesn't just react to your messages. In Background Mode, it proactively checks the weather on a schedule, reasons about whether it's a good time to nudge you, and only reaches out when conditions are right. It won't spam you — a cooldown system prevents the same type of nudge within an hour.
| Provider | Model Example | Free Tier? | Setup |
|---|---|---|---|
| Groq | llama-3.1-8b-instant |
✅ Yes | console.groq.com |
| OpenAI | gpt-4o-mini |
❌ Paid | platform.openai.com |
| Google Gemini | gemini-pro |
✅ Free tier | aistudio.google.com |
| Anthropic Claude | claude-sonnet-4-20250514 |
❌ Paid | console.anthropic.com |
| Ollama (local) | llama3, mistral |
✅ Free (local) | ollama.com |
| LM Studio (local) | any GGUF model | ✅ Free (local) | lmstudio.ai |
breeze-buddy/
├── frontend/
│ ├── index.html # WhatsApp-style chat UI
│ ├── style.css # All styling
│ ├── app.js # Chat logic + background mode
│ ├── settings.js # Settings panel with auto-save
│ ├── notifications.js # Browser notifications + polling
│ ├── sw.js # Service worker for background notifications
│ └── assets/
│ └── bg-mode.gif # Background mode illustration
├── backend/
│ ├── main.py # FastAPI server (7 routes)
│ ├── llm/
│ │ ├── provider_router.py # LiteLLM multi-provider wrapper
│ │ └── prompts.py # System prompts for 6 personalities
│ ├── weather/
│ │ └── open_meteo.py # Open-Meteo API client with caching
│ ├── memory/
│ │ └── preferences.py # JSON read/write for user preferences
│ └── agent/
│ ├── decision_engine.py # ReAct loop + safety gate
│ └── tools.py # Agent tool definitions + dispatcher
├── data/
│ └── user_preferences.json # Your settings + history (gitignored)
├── scripts/
│ ├── run_local.sh / .ps1 # One-command launcher
│ └── run_tunnel.sh / .ps1 # Cloudflare tunnel launcher
├── pyproject.toml # Dependencies (uv/pip)
└── .env.example # Optional env defaults
Don't want to chat? Enable Background Mode in Settings. BreezyBuddy collapses to a minimal weather card with a cultural illustration backdrop. It silently checks the weather on your schedule and sends desktop notifications when conditions are right — like Zomato nudging you to order food.
How it works:
- Configure your settings (API key, location, personality)
- Toggle Background Mode in Settings
- Minimize the tab and go about your day
- Get nudged via desktop notification when conditions are perfect
# Linux/macOS
bash scripts/run_tunnel.sh
# Windows
.\scripts\run_tunnel.ps1This gives you a public URL you can open on your phone or share with friends. Requires cloudflared.
BreezyBuddy is a single-user local app — it trusts whoever is at the keyboard. Known limitations:
- 🔑 API keys stored in plain text in
data/user_preferences.json(gitignored, but be careful with screenshots and syncs). - 📍 Coordinates sent to Open-Meteo to fetch weather. No auth or API key required by the service, but the coordinates do leave your machine.
- 💬 Chat history (last 50 entries) stored in cleartext in the same JSON file.
- 🔓 No authentication on the local server. Anything that can reach
http://localhost:8000can read your settings and use your LLM quota. - 🛡️ Prompt-injection mitigation is soft. Two layers — a regex sanitizer in
/api/chatthat neutralizes phrasings like "ignore previous", "system prompt", "you are now…", and a system-prompt directive that tells the model to refuse such requests. Determined attacks can still slip through. - 🌐 Cloudflare Tunnel URLs are public — no auth in front of them. Treat the URL like the API key behind it.
- Auto-reload:
cd backend && uvicorn main:app --reload --port 8000 - Force a nudge check now: press
Ctrl + Alt + Nanywhere on the page - Read the source. Every file is heavily commented — the agent is written to teach as much as to run.
This is a beginner-friendly project. If you're learning about AI agents, you're the target contributor.
Ways to contribute:
- Add a new personality mode
- Add a new language
- Improve the agent's decision logic
- Add new nudge types (hydration, UV warning, exercise)
- Better notification scheduling
- Bug fixes and UX improvements
MIT — use it, learn from it, build on it. See LICENSE.
Built with ☕ and curiosity by Sasikumar Krishnan. Part of Saturday AI Club — where we solve real problems with AI every weekend.