Initial commit

Initial commit of FocusFlow AI productivity helper

.env.example

@@ -0,0 +1,60 @@
+# FocusFlow Environment Configuration
+# Copy this file to .env and fill in your values
+
+# Launch Mode
+# - demo: Uses text area for workspace monitoring (ideal for HuggingFace Spaces)
+# - local: Monitors actual file system changes
+LAUNCH_MODE=demo
+
+# AI Provider
+# Options: openai, anthropic, gemini, vllm, mock
+AI_PROVIDER=anthropic
+
+# Monitoring Settings
+MONITOR_INTERVAL=30  # Seconds between automatic focus checks
+
+# MCP Server
+ENABLE_MCP=true  # Enable Model Context Protocol server
+
+# ===== AI Provider API Keys =====
+
+# OpenAI (GPT-4)
+# Get your key from: https://platform.openai.com/api-keys
+OPENAI_API_KEY=
+
+# Anthropic (Claude)
+# Get your key from: https://console.anthropic.com/
+ANTHROPIC_API_KEY=
+
+# Google Gemini
+# Get your key from: https://makersuite.google.com/app/apikey
+GEMINI_API_KEY=
+
+# vLLM (Local Inference)
+VLLM_BASE_URL=http://localhost:8000/v1
+VLLM_MODEL=ibm-granite/granite-4.0-h-1b
+VLLM_API_KEY=EMPTY
+
+# ===== Demo API Keys (For Hackathon Organizers) =====
+# These are checked FIRST before user keys
+# Set these on HuggingFace Spaces to enable AI for judges/testers
+# Falls back to Mock AI if keys are invalid or out of credits
+
+DEMO_ANTHROPIC_API_KEY=
+DEMO_OPENAI_API_KEY=
+DEMO_GEMINI_API_KEY=
+
+# ===== ElevenLabs Voice Integration (Optional) =====
+# Get your key from: https://elevenlabs.io/
+# Voice feedback is OPTIONAL - app works perfectly without it
+
+ELEVEN_API_KEY=
+DEMO_ELEVEN_API_KEY=
+
+# Voice settings (optional)
+VOICE_ENABLED=true  # Set to false to disable voice globally
+
+# ===== Notes =====
+# - Leave API keys empty to use Mock AI (demo mode)
+# - Demo keys are perfect for hackathon deployments
+# - App gracefully degrades to Mock AI on any errors

README.md

@@ -1,17 +1,730 @@
+# 🦉 FocusFlow - AI Productivity Accountability Agent
+
+**Your Duolingo-style AI buddy that keeps you focused while coding**
+
+[![Gradio](https://img.shields.io/badge/Built%20with-Gradio-orange)](https://gradio.app)
+[![MCP](https://img.shields.io/badge/MCP-Enabled-blue)](https://modelcontextprotocol.io)
+[![Python](https://img.shields.io/badge/Python-3.11+-green)](https://python.org)
+
+## 🎯 The Problem
+
+Developers with ADHD and procrastination tendencies struggle with:
+- **Task paralysis**: Breaking projects into manageable pieces
+- **Context switching**: Getting distracted by unrelated files/tasks
+- **Accountability**: No one keeping them on track during work sessions
+- **Progress tracking**: Not knowing if they're making real progress
+
+## ✨ The Solution
+
+FocusFlow is an AI-powered productivity partner that:
+1. **Breaks down projects** into 5-8 micro-tasks (15-30 min each)
+2. **Monitors your workspace** in real-time (file changes or text input)
+3. **Provides Duolingo-style nudges** when you get distracted or idle
+4. **Tracks focus metrics** with streaks, scores, and visualizations
+5. **Integrates with LLMs** via MCP (Model Context Protocol) for natural language task management
+
+## 🚀 Key Features
+
+### 🎯 AI-Powered Project Onboarding
+- Describe your project in plain English
+- Get actionable micro-tasks instantly
+- Smart task generation based on project type (web, API, etc.)
+
+### 👁️ Real-Time Focus Monitoring
+- **Local Mode**: Watches your project directory for file changes
+- **Demo Mode**: Simulates workspace with text area (perfect for HuggingFace Spaces)
+- Content-aware analysis (reads code changes, not just filenames)
+
+### 🦉 Duolingo-Style Personality
+- **On Track**: "Great work! You're making solid progress! 🎯"
+- **Distracted**: "Wait, what are you working on? That doesn't look like the task! 🤨"
+- **Idle**: "Files won't write themselves. *Hoot hoot.* 🦉"
+
+### 📊 Productivity Dashboard
+- **Focus Score**: 0-100 rating based on on-track percentage
+- **Streaks**: Consecutive "On Track" checks 🔥
+- **Weekly Trends**: Visualize your focus patterns
+- **State Distribution**: See where your time goes
+
+### 🍅 Built-in Pomodoro Timer
+- 25-minute work sessions
+- 5-minute break reminders
+- Audio alerts + browser notifications
+- Auto-switching between work and break modes
+
+### 🔗 MCP Integration (Game Changer!)
+Connect FocusFlow to Claude Desktop, Cursor, or any MCP-compatible client!
+
+**Available MCP Tools:**
+- `add_task(title, description, duration)` - Create tasks via conversation
+- `get_current_task()` - Check what you should be working on
+- `start_task(task_id)` - Begin a focus session
+- `mark_task_done(task_id)` - Complete tasks
+- `get_all_tasks()` - List all tasks
+- `get_productivity_stats()` - View your metrics
+
+**MCP Resources:**
+- `focusflow://tasks/all` - Full task list
+- `focusflow://tasks/active` - Current active task
+- `focusflow://stats` - Productivity statistics
+
+## 📦 Installation
+
+### Quick Start (Demo Mode)
+
+```bash
+# Clone the repository
+git clone https://github.com/Rebell-Leader/FocusFlow.git
+cd FocusFlow
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run in demo mode (no API keys needed!)
+python app.py
+```
+
+Open `http://localhost:5000` in your browser.
+
+### With AI Provider (Optional)
+
+FocusFlow supports multiple AI providers:
+
+```bash
+# Option 1: OpenAI
+export AI_PROVIDER=openai
+export OPENAI_API_KEY=your_key_here
+
+# Option 2: Anthropic Claude
+export AI_PROVIDER=anthropic
+export ANTHROPIC_API_KEY=your_key_here
+
+# Option 3: Google Gemini
+export AI_PROVIDER=gemini
+export GEMINI_API_KEY=your_key_here
+
+# Option 4: vLLM (local inference)
+export AI_PROVIDER=vllm
+export VLLM_BASE_URL=http://localhost:8000/v1
+export VLLM_MODEL=ibm-granite/granite-4.0-h-1b
+
+# Then run
+python app.py
+```
+
+**No API keys? No problem!** FocusFlow automatically uses a **Mock AI** agent with predefined responses for testing.
+
+### For Hackathon Organizers (HuggingFace Spaces)
+
+To enable AI features on demo deployments, set **demo API keys** as environment variables:
+
+```bash
+DEMO_ANTHROPIC_API_KEY=sk-ant-xxx  # Checked first, falls back to user keys
+DEMO_OPENAI_API_KEY=sk-xxx         # Same fallback logic
+DEMO_GEMINI_API_KEY=xxx            # Same fallback logic
+```
+
+If demo keys run out of credits, FocusFlow gracefully falls back to Mock AI mode automatically.
+
+## 🔌 Connecting to Claude Desktop (MCP)
+
+### Step 1: Start FocusFlow
+
+```bash
+python app.py
+```
+
+You'll see:
+```
+🔗 MCP Server enabled! Connect via Claude Desktop or other MCP clients.
+* Streamable HTTP URL: http://localhost:5000/gradio_api/mcp/
+```
+
+### 🔌 Connecting via MCP (Claude Desktop / Windows)
+
+FocusFlow runs an MCP server that you can connect to from external tools like Claude Desktop or LM Studio.
+
+**If running on WSL and connecting from Windows:**
+
+1.  **Ensure the app is running**: `python app.py` (it listens on `0.0.0.0` by default).
+2.  **Find your WSL IP address**: Run `wsl hostname -I` in your terminal.
+3.  **Configure your MCP Client**:
+    *   **Type**: SSE (Server-Sent Events)
+    *   **URL**: `http://<YOUR_WSL_IP>:5000/gradio_api/mcp/sse`
+    *   *(Or try `http://localhost:5000/gradio_api/mcp/sse` if localhost forwarding is working)*
+
+**Available MCP Tools:**
+*   `get_active_task`: Get the currently active task.
+*   `add_task`: Create a new task.
+*   `update_task`: Update task status or details.
+*   `get_productivity_stats`: Get focus scores and metrics.
+
+**Configuration (mcp.json / claude_desktop_config.json):**
+
+```json
+{
+  "mcpServers": {
+    "focusflow": {
+      "url": "http://<YOUR_WSL_IP>:5000/gradio_api/mcp/sse"
+    }
+  }
+}
+```
+*Replace `<YOUR_WSL_IP>` with the IP address from step 2 (e.g., `172.x.x.x`).*
+
+### Step 2: Configure Claude Desktop
+
+#### macOS
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "focusflow": {
+      "command": "python",
+      "args": ["/absolute/path/to/your/focusflow/app.py"]
+    }
+  }
+}
+```
+
+#### Windows
+Edit `%APPDATA%\Claude\claude_desktop_config.json` with the same JSON format.
+
+### Step 3: Restart Claude Desktop
+
+Close and reopen Claude Desktop. You should see FocusFlow tools available!
+
+### Step 4: Test It Out
+
+In Claude Desktop, try:
+```
+"Add a task to build a REST API with authentication"
+"What task should I work on now?"
+"Mark task 1 as done"
+"Show me my productivity stats"
+```
+
+## 🆕 Recent Updates
+
+### Version 1.0 (Hackathon Release)
+- ✅ **MCP Integration** - Full Model Context Protocol support with 8 tools and 3 resources
+- ✅ **Voice Feedback** - ElevenLabs integration for Duolingo-style audio nudges
+- ✅ **Demo API Keys** - Support for `DEMO_ANTHROPIC_API_KEY`, `DEMO_OPENAI_API_KEY`, and `DEMO_ELEVEN_API_KEY` for hackathon deployments
+- ✅ **Productivity Dashboard** - Focus scores, streaks, weekly trends, and state distribution charts
+- ✅ **Mock AI Mode** - Works without API keys for testing and demos
+- ✅ **Graceful Degradation** - Automatically falls back to Mock AI if API keys are invalid or out of credits
+- ✅ **Dual Launch Modes** - Demo mode (text area) and Local mode (file monitoring)
+- ✅ **Comprehensive Testing** - Full testing checklist in `TESTING_CHECKLIST.md`
+- ✅ **Error Handling** - Invalid task IDs return helpful error messages in MCP tools
+- ✅ **Metrics Integration** - MCP `get_productivity_stats()` includes focus scores and streaks
+
+## ⚙️ Configuration & Environment Variables
+
+### Core Settings
+
+| Variable | Default | Options | Description |
+|----------|---------|---------|-------------|
+| `LAUNCH_MODE` | `demo` | `demo`, `local` | Workspace monitoring mode (see Launch Modes below) |
+| `AI_PROVIDER` | `anthropic` | `openai`, `anthropic`, `vllm`, `mock` | AI provider to use |
+| `MONITOR_INTERVAL` | `30` | Any integer | Seconds between automatic focus checks |
+| `ENABLE_MCP` | `true` | `true`, `false` | Enable/disable MCP server |
+
+### AI Provider API Keys
+
+**Priority Order:** Demo keys are checked first, then user keys, then falls back to Mock AI.
+
+#### User API Keys
+| Variable | Description | Get Key From |
+|----------|-------------|--------------|
+| `OPENAI_API_KEY` | Your personal OpenAI API key | https://platform.openai.com/api-keys |
+| `ANTHROPIC_API_KEY` | Your personal Anthropic API key | https://console.anthropic.com/ |
+| `ELEVEN_API_KEY` | Your personal ElevenLabs API key (optional) | https://elevenlabs.io/api |
+| `LINEAR_API_KEY` | Your personal Linear API key (optional) | https://linear.app/settings/api |
+
+#### Demo API Keys (For Hackathon Organizers)
+| Variable | Description | Use Case |
+|----------|-------------|----------|
+| `DEMO_ANTHROPIC_API_KEY` | Shared Anthropic key for demos | Set on HuggingFace Spaces for judges/testers |
+| `DEMO_OPENAI_API_KEY` | Shared OpenAI key for demos | Set on HuggingFace Spaces for judges/testers |
+| `DEMO_ELEVEN_API_KEY` | Shared ElevenLabs key for voice | Set on HuggingFace Spaces for voice feedback |
+
+**How It Works:**
+```python
+# Priority chain (Anthropic example):
+1. Check DEMO_ANTHROPIC_API_KEY (hackathon demo key)
+2. If not found, check ANTHROPIC_API_KEY (user's personal key)
+3. If not found or invalid, fall back to Mock AI (no errors!)
+
+# Voice integration (optional):
+1. Check DEMO_ELEVEN_API_KEY (hackathon demo key)
+2. If not found, check ELEVEN_API_KEY (user's personal key)
+3. If not found, gracefully disable voice (text-only mode)
+```
+
+#### vLLM Settings (Local Inference)
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VLLM_BASE_URL` | `http://localhost:8000/v1` | vLLM server endpoint |
+| `VLLM_MODEL` | `ibm-granite/granite-4.0-h-1b` | Model name |
+| `VLLM_API_KEY` | `EMPTY` | API key (usually not needed for local) |
+
+### API Key Management Best Practices
+
+**For Local Development:**
+```bash
+# Copy the example file
+cp .env.example .env
+
+# Edit .env and add your personal keys
+nano .env  # or your preferred editor
+```
+
+**For HuggingFace Spaces Deployment:**
+```bash
+# In Space Settings > Variables, add:
+LAUNCH_MODE=demo
+AI_PROVIDER=anthropic
+DEMO_ANTHROPIC_API_KEY=sk-ant-your-hackathon-key
+```
+
+**For Testing Without API Keys:**
+```bash
+# Just run - Mock AI activates automatically!
+python app.py
+# Status: "ℹ️ Running in DEMO MODE with Mock AI (no API keys needed). Perfect for testing! 🎭"
+```
+
+### Graceful Degradation
+
+FocusFlow **never crashes** due to missing or invalid API keys:
+
+| Scenario | Behavior | User Experience |
+|----------|----------|-----------------|
+| No API keys set | Uses Mock AI | ✅ Full demo functionality |
+| Invalid API key | Falls back to Mock AI | ✅ App continues working |
+| API out of credits | Falls back to Mock AI | ✅ Seamless transition |
+| API rate limited | Retries, then Mock AI | ✅ No interruption |
+
+**Status Messages:**
+- `✅ Anthropic Claude initialized successfully (demo key)` - Demo key working
+- `✅ OpenAI GPT-4 initialized successfully (user key)` - User key working
+- `ℹ️ Running in DEMO MODE with Mock AI (no API keys needed)` - Fallback active
+
+## 🎮 Launch Modes Explained
+
+FocusFlow supports two workspace monitoring modes:
+
+### Demo Mode (`LAUNCH_MODE=demo`)
+
+**Best for:**
+- HuggingFace Spaces deployments
+- Replit deployments
+- Testing without file system access
+- Hackathon demos for judges
+
+**How it works:**
+- Provides a text area for simulating workspace activity
+- Users type what they're working on
+- AI analyzes text content for focus checks
+- No file system permissions needed
+
+**Example:**
+```bash
+export LAUNCH_MODE=demo
+python app.py
+# Monitor tab shows: "Demo Workspace" text area
+```
+
+**User Workflow:**
+1. Type: "Working on authentication API, creating login endpoint"
+2. Click "Check Focus Now"
+3. Result: "On Track! Great work! 🎯"
+
+### Local Mode (`LAUNCH_MODE=local`)
+
+**Best for:**
+- Local development environments
+- Real-time file monitoring
+- Production use cases
+- Personal productivity tracking
+
+**How it works:**
+- Uses `watchdog` library to monitor file system changes
+- Automatically detects file modifications in project directory
+- Reads actual file diffs for intelligent analysis
+- Triggers focus checks automatically when files change
+
+**Example:**
+```bash
+export LAUNCH_MODE=local
+python app.py
+# Monitor tab shows: "Watching directory: /your/project/path"
+```
+
+**User Workflow:**
+1. Start a task in Task Manager
+2. Edit files in your project
+3. FocusFlow automatically detects changes and runs focus checks
+4. Receive real-time feedback
+
+### Choosing the Right Mode
+
+| Use Case | Recommended Mode | Reason |
+|----------|------------------|--------|
+| HuggingFace Spaces | `demo` | No file system access in web deployments |
+| Hackathon demo | `demo` | Easy for judges to test without setup |
+| Local development | `local` | Real-time file monitoring is more natural |
+| Replit | `demo` | Simpler, no file permissions issues |
+| Personal productivity | `local` | Authentic workspace monitoring |
+
+## 📁 Project Structure
+
+```
+focusflow/
+├── app.py              # Main Gradio application
+├── agent.py            # AI focus agent (OpenAI/Anthropic/Mock)
+├── storage.py          # Task manager with SQLite
+├── monitor.py          # File monitoring with watchdog
+├── metrics.py          # Productivity tracking
+├── mcp_tools.py        # MCP tools and resources
+├── requirements.txt    # Python dependencies
+├── .env.example        # Environment template
+└── README.md           # This file
+```
+
+## 🎥 Demo & Screenshots
+
+### Home Screen
+Clean interface with feature overview and configuration status.
+
+### Onboarding
+AI generates micro-tasks from project descriptions.
+
+### Task Manager
+Kanban-style task board with drag-and-drop (coming soon).
+
+### Dashboard
+Visualize focus scores, streaks, and productivity trends.
+
+### Monitor
+Real-time focus checks with Duolingo-style feedback.
+
+## 🏆 Why This is Perfect for the Gradio MCP Hackathon
+
+1. **Novel MCP Use Case**: First MCP-powered productivity/accountability tool
+2. **Deep Integration**: Natural language task management through Claude Desktop
+3. **Real Problem**: Solves actual pain points for developers with ADHD
+4. **Gradio Showcase**: Uses tabs, plots, timers, state management, custom JS
+5. **Demo-Friendly**: Works without API keys, deployable to HF Spaces
+6. **Production-Ready**: SQLite persistence, metrics tracking, error handling
+
+## 🧪 Testing
+
+### Quick Feature Test (5 minutes)
+
+Use the comprehensive **`TESTING_CHECKLIST.md`** file for detailed testing instructions. Here's a quick verification:
+
+```bash
+# 1. Start the app
+python app.py
+
+# 2. Open browser
+open http://localhost:5000
+
+# 3. Test each tab:
+# ✅ Home: Check status message shows AI provider
+# ✅ Onboarding: Generate tasks from project description
+# ✅ Task Manager: Create/edit/delete/start tasks
+# ✅ Monitor: Perform focus checks (demo workspace or file changes)
+# ✅ Dashboard: View metrics after focus checks
+# ✅ Pomodoro: Start/pause/reset timer
+```
+
+### Test Scenarios
+
+**Scenario 1: Demo Mode (No API Keys)**
+```bash
+# No .env file needed
+python app.py
+# Expected: "ℹ️ Running in DEMO MODE with Mock AI"
+# Test: All features work with predefined responses
+```
+
+**Scenario 2: With Anthropic API Key**
+```bash
+export AI_PROVIDER=anthropic
+export ANTHROPIC_API_KEY=sk-ant-your-key
+python app.py
+# Expected: "✅ Anthropic Claude initialized successfully (user key)"
+# Test: Intelligent task generation and focus analysis
+```
+
+**Scenario 3: Demo Key (Hackathon Deployment)**
+```bash
+export AI_PROVIDER=anthropic
+export DEMO_ANTHROPIC_API_KEY=sk-ant-demo-key
+python app.py
+# Expected: "✅ Anthropic Claude initialized successfully (demo key)"
+# Test: Uses demo key, falls back to Mock if exhausted
+```
+
+**Scenario 4: MCP Integration**
+```bash
+# 1. Configure Claude Desktop (see MCP section above)
+# 2. Start FocusFlow
+python app.py
+# 3. In Claude Desktop, test tools:
+#    - "Add a task to implement OAuth2"
+#    - "What's my current task?"
+#    - "Show my productivity stats"
+```
+
+### Automated Testing
+
+Run the full test suite:
+```bash
+# Follow TESTING_CHECKLIST.md step-by-step
+# Expected: All features pass without errors
+# Time: ~15 minutes for comprehensive test
+```
+
+### Common Issues & Solutions
+
+| Issue | Solution |
+|-------|----------|
+| "No API key" error | Set `AI_PROVIDER=mock` or leave keys empty - Mock AI activates automatically |
+| Charts show "Infinite extent" warning | Normal on first load with no data - warnings disappear after focus checks |
+| MCP tools not visible in Claude | Restart Claude Desktop after config changes |
+| File monitoring not working | Check `LAUNCH_MODE=local` and file permissions |
+| Tasks not persisting | Check `focusflow.db` file exists and is writable |
+
+## 🚀 Deployment
+
+### Deployment Option 1: HuggingFace Spaces (Recommended for Hackathon)
+
+**Step 1: Create Space**
+1. Go to https://huggingface.co/spaces
+2. Click "Create new Space"
+3. Select "Gradio" as SDK
+4. Choose a name (e.g., `focusflow-demo`)
+
+**Step 2: Upload Files**
+Upload these files to your Space:
+- `app.py`
+- `agent.py`
+- `storage.py`
+- `monitor.py`
+- `metrics.py`
+- `mcp_tools.py`
+- `requirements.txt`
+- `README.md`
+- `.env.example` (optional, for documentation)
+
+**Step 3: Configure Environment Variables**
+
+In Space Settings → Variables, add:
+
+**Option A: With Demo AI (Recommended for Judges)**
+```bash
+LAUNCH_MODE=demo
+AI_PROVIDER=anthropic
+DEMO_ANTHROPIC_API_KEY=sk-ant-your-hackathon-shared-key
+MONITOR_INTERVAL=30
+ENABLE_MCP=true
+```
+
+**Option B: Mock AI Only (No API Keys Needed)**
+```bash
+LAUNCH_MODE=demo
+AI_PROVIDER=mock
+MONITOR_INTERVAL=30
+ENABLE_MCP=true
+```
+
+**Step 4: Deploy**
+- Click "Save" - Space will automatically rebuild and deploy
+- Your app will be live at: `https://huggingface.co/spaces/yourusername/focusflow-demo`
+- MCP server endpoint: `https://yourusername-focusflow-demo.hf.space/gradio_api/mcp/`
+
+**Step 5: Test Deployment**
+1. Open the Space URL
+2. Test onboarding → Generate tasks
+3. Test task manager → CRUD operations
+4. Test monitor → Focus checks
+5. Test dashboard → View metrics
+6. Test MCP (optional) → Connect from Claude Desktop
+
+### Deployment Option 2: Replit
+
+**Step 1: Import Repository**
+1. Go to https://replit.com
+2. Click "Create Repl" → "Import from GitHub"
+3. Paste your FocusFlow repository URL
+
+**Step 2: Configure Secrets**
+In Replit Secrets (Tools → Secrets):
+```bash
+AI_PROVIDER=anthropic
+ANTHROPIC_API_KEY=your_key_here
+LAUNCH_MODE=demo
+```
+
+**Step 3: Run**
+```bash
+python app.py
+```
+
+**Step 4: Share**
+- Click "Share" button
+- Copy the public URL
+- MCP endpoint: `https://yourrepl.repl.co/gradio_api/mcp/`
+
+### Deployment Option 3: Local Development
+
+**Step 1: Clone Repository**
+```bash
+git clone https://github.com/yourusername/focusflow.git
+cd focusflow
+```
+
+**Step 2: Install Dependencies**
+```bash
+pip install -r requirements.txt
+```
+
+**Step 3: Configure Environment**
+```bash
+# Copy example
+cp .env.example .env
+
+# Edit .env with your settings
+nano .env  # or code .env, vim .env, etc.
+```
+
+**Step 4: Run**
+```bash
+# For local file monitoring
+export LAUNCH_MODE=local
+python app.py
+
+# For demo mode (text area)
+export LAUNCH_MODE=demo
+python app.py
+```
+
+**Step 5: Access**
+- Web UI: http://localhost:5000
+- MCP endpoint: http://localhost:5000/gradio_api/mcp/
+
+### Deployment Option 4: Docker (Advanced)
+
+Create `Dockerfile`:
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+ENV LAUNCH_MODE=demo
+ENV AI_PROVIDER=mock
+ENV ENABLE_MCP=true
+
+EXPOSE 5000
+
+CMD ["python", "app.py"]
+```
+
+Build and run:
+```bash
+docker build -t focusflow .
+docker run -p 5000:5000 -e ANTHROPIC_API_KEY=your_key focusflow
+```
+
+### Post-Deployment Checklist
+
+After deploying to any platform:
+
+- [ ] App loads without errors
+- [ ] Home tab shows correct AI provider status
+- [ ] Onboarding generates tasks
+- [ ] Task Manager CRUD operations work
+- [ ] Monitor tab performs focus checks
+- [ ] Dashboard displays metrics (after checks)
+- [ ] Pomodoro timer functions
+- [ ] MCP endpoint accessible (optional)
+- [ ] No sensitive data exposed in logs
+- [ ] Database file (`focusflow.db`) created successfully
+
+### Environment Variables Reference (Deployment)
+
+**Required:**
+- `LAUNCH_MODE` - Always set to `demo` for web deployments
+
+**Optional:**
+- `AI_PROVIDER` - `anthropic`, `openai`, `vllm`, or `mock` (default: `anthropic`)
+- `DEMO_ANTHROPIC_API_KEY` - For hackathon/shared deployments
+- `DEMO_OPENAI_API_KEY` - Alternative demo provider
+- `ANTHROPIC_API_KEY` - User's personal key
+- `OPENAI_API_KEY` - User's personal key
+- `MONITOR_INTERVAL` - Seconds between checks (default: 30)
+- `ENABLE_MCP` - Enable MCP server (default: true)
+
+### Deployment Troubleshooting
+
+| Issue | Platform | Solution |
+|-------|----------|----------|
+| Import errors | HF Spaces | Check `requirements.txt` includes all dependencies |
+| "Port already in use" | Local | Change port in `app.py` or kill process using port 5000 |
+| MCP not accessible | All | Ensure `ENABLE_MCP=true` and check firewall settings |
+| Database errors | HF Spaces | Ensure space has write permissions (SQLite needs filesystem) |
+| Mock AI always active | All | Check environment variables are set correctly |
+| Slow performance | HF Spaces | Free tier has limited resources - consider upgrading |
+
+## 🛠️ Tech Stack
+
+- **Frontend**: Gradio 5.0+ (Python UI framework)
+- **Backend**: Python 3.11+
+- **Database**: SQLite (zero-config persistence)
+- **AI Providers**: OpenAI GPT-4, Anthropic Claude, Google Gemini, vLLM, or Mock
+- **Voice**: ElevenLabs text-to-speech (optional)
+- **File Monitoring**: Watchdog (real-time filesystem events)
+- **MCP Integration**: Model Context Protocol for LLM interoperability
+- **Charts**: Gradio native plots (pandas DataFrames)
+
+## 📈 Roadmap
+
+- [ ] Mobile app (React Native + Gradio backend)
+- [ ] GitHub integration (auto-detect tasks from issues)
+- [ ] Slack/Discord notifications
+- [ ] Team mode (shared accountability)
+- [ ] Voice commands (Whisper integration)
+- [ ] VS Code extension
+
+## 🤝 Contributing
+
+Contributions welcome! Please:
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## 📄 License
+
+MIT License - feel free to use this for personal or commercial projects!
+
+## 🙏 Acknowledgments
+
+- Built for the [Gradio MCP Hackathon](https://gradio.app) - competing for **Track 1: Building MCP**
+- Voice integration powered by [ElevenLabs](https://elevenlabs.io) - competing for **$2,000 Best Use of ElevenLabs** sponsor award
+- Inspired by Duolingo's encouraging UX
+- Uses [Model Context Protocol](https://modelcontextprotocol.io) for LLM integration
+
 ---
-title: FocusFlowAI
-emoji: 💬
-colorFrom: yellow
-colorTo: purple
-sdk: gradio
-sdk_version: 5.42.0
-app_file: app.py
-pinned: false
-hf_oauth: true
-hf_oauth_scopes:
-- inference-api
-license: mit
-short_description: FocusFlow, an AI productivity companion + task tracker
----
 
-An example chatbot using [Gradio](https://gradio.app), [`huggingface_hub`](https://huggingface.co/docs/huggingface_hub/v0.22.2/en/index), and the [Hugging Face Inference API](https://huggingface.co/docs/api-inference/index).
+**Made with ❤️ for developers with ADHD who just need a little nudge to stay focused.**
+
+*Hoot hoot!* 🦉

agent.py

@@ -0,0 +1,404 @@
+"""
+AI Focus Agent with OpenAI/Claude integration and personality system.
+"""
+import os
+from typing import Dict, List, Optional, Union
+from datetime import datetime
+import json
+
+
+class FocusAgent:
+    """AI agent that monitors focus and provides Duolingo-style nudges."""
+
+    def __init__(self, provider: str = "openai", api_key: Optional[str] = None,
+                 base_url: Optional[str] = None, model: Optional[str] = None):
+        """Initialize the focus agent with AI provider."""
+        self.provider = provider.lower()
+        self.last_verdict: Optional[str] = None
+        self.idle_count = 0
+        self.distracted_count = 0
+        self.connection_healthy = False
+
+        if self.provider == "openai":
+            from openai import OpenAI
+            self.api_key = api_key or os.getenv("OPENAI_API_KEY")
+            self.client = OpenAI(api_key=self.api_key) if self.api_key else None
+            self.model = model or "gpt-4o"
+            self.connection_healthy = bool(self.api_key)
+        elif self.provider == "anthropic":
+            from anthropic import Anthropic
+            self.api_key = api_key or os.getenv("ANTHROPIC_API_KEY")
+            self.client = Anthropic(api_key=self.api_key) if self.api_key else None
+            self.model = model or "claude-haiku-4-5-20251001"
+            self.connection_healthy = bool(self.api_key)
+        elif self.provider == "gemini":
+            import google.generativeai as genai
+            self.api_key = api_key or os.getenv("GEMINI_API_KEY")
+            if self.api_key:
+                genai.configure(api_key=self.api_key)
+                self.client = genai.GenerativeModel(model or "gemini-2.0-flash-exp")
+                self.model = model or "gemini-2.0-flash-exp"
+                self.connection_healthy = True
+            else:
+                self.client = None
+                self.connection_healthy = False
+        elif self.provider == "vllm":
+            from openai import OpenAI
+            import httpx
+            self.api_key = api_key or os.getenv("VLLM_API_KEY", "EMPTY")
+            self.base_url = base_url or os.getenv("VLLM_BASE_URL", "http://localhost:8000/v1")
+            self.model = model or os.getenv("VLLM_MODEL", "ibm-granite/granite-4.0-h-1b")
+
+            try:
+                timeout = httpx.Timeout(5.0, connect=2.0)
+                self.client = OpenAI(api_key=self.api_key, base_url=self.base_url, timeout=timeout)
+                test_response = self.client.models.list()
+                self.connection_healthy = True
+            except Exception as e:
+                print(f"⚠️ vLLM connection failed: {e}")
+                print(f"   Make sure vLLM server is running at {self.base_url}")
+                self.client = None
+                self.connection_healthy = False
+        else:
+            raise ValueError(f"Unsupported provider: {provider}. Supported: openai, anthropic, gemini, vllm")
+
+    def _create_analysis_prompt(self, active_task: Dict, recent_activity: List[Dict]) -> str:
+        """Create the analysis prompt for the LLM."""
+        if not recent_activity:
+            return f"""You are FocusFlow, a Duolingo-style accountability buddy for developers.
+
+**Current Task:**
+- Title: {active_task.get('title', 'No task')}
+- Description: {active_task.get('description', 'No description')}
+
+**Recent Activity:** No file changes detected in the last 60 seconds.
+
+**Your Job:** Analyze the situation and respond with ONE of these verdicts:
+1. "On Track" - If there's activity related to the task
+2. "Distracted" - If files unrelated to the task are being edited
+3. "Idle" - If there's no activity
+
+Respond in JSON format:
+{{
+  "verdict": "On Track" | "Distracted" | "Idle",
+  "message": "Your encouraging/sassy/nudging message (1-2 sentences, Duolingo style)",
+  "reasoning": "Brief explanation of your analysis"
+}}"""
+
+        activity_summary = []
+        for event in recent_activity[-5:]:
+            activity_summary.append(
+                f"- {event['type'].upper()}: {event['filename']}\n  Content: {event.get('content', 'N/A')[:200]}"
+            )
+
+        activity_text = "\n".join(activity_summary)
+
+        return f"""You are FocusFlow, a Duolingo-style accountability buddy for developers.
+
+**Current Task:**
+- Title: {active_task.get('title', 'No task')}
+- Description: {active_task.get('description', 'No description')}
+
+**Recent File Activity (last 60 seconds):**
+{activity_text}
+
+**Your Job:** Analyze if the file changes are related to the current task.
+
+**Personality Guidelines:**
+- "On Track": Be encouraging and specific (e.g., "Great job! I see you're working on the login form!")
+- "Distracted": Be playfully sassy (e.g., "Wait, why are you editing random_file.py? We're building a Snake game! 🤨")
+- "Idle": Be gently nudging (e.g., "Files won't write themselves. *Hoot hoot.* 🦉")
+
+Respond in JSON format:
+{{
+  "verdict": "On Track" | "Distracted" | "Idle",
+  "message": "Your message (1-2 sentences)",
+  "reasoning": "Brief explanation"
+}}"""
+
+    def _call_llm(self, prompt: str) -> Dict:
+        """Call the LLM and parse the response."""
+        try:
+            if self.provider in ["openai", "vllm"]:
+                if not self.client:
+                    return {"verdict": "On Track", "message": "API client not initialized", "reasoning": "No client"}
+                response = self.client.chat.completions.create(
+                    model=self.model,
+                    messages=[{"role": "user", "content": prompt}],
+                    temperature=0.7,
+                    max_tokens=300
+                )
+                content = response.choices[0].message.content
+            elif self.provider == "gemini":
+                if not self.client:
+                    return {"verdict": "On Track", "message": "API client not initialized", "reasoning": "No client"}
+                response = self.client.generate_content(
+                    prompt,
+                    generation_config={
+                        "temperature": 0.7,
+                        "max_output_tokens": 300,
+                    }
+                )
+                content = response.text
+            else:  # anthropic
+                if not self.client:
+                    return {"verdict": "On Track", "message": "API client not initialized", "reasoning": "No client"}
+                response = self.client.messages.create(
+                    model=self.model,
+                    max_tokens=300,
+                    temperature=0.7,
+                    messages=[{"role": "user", "content": prompt}]
+                )
+                content = response.content[0].text
+
+            if not content:
+                return {"verdict": "On Track", "message": "Empty response from API", "reasoning": "No content"}
+
+            # Try to parse JSON from the response
+            content = content.strip()
+            if "```json" in content:
+                content = content.split("```json")[1].split("```")[0].strip()
+            elif "```" in content:
+                content = content.split("```")[1].split("```")[0].strip()
+
+            result = json.loads(content)
+            return result
+
+        except json.JSONDecodeError:
+            # Fallback if JSON parsing fails
+            return {
+                "verdict": "On Track",
+                "message": content[:200],
+                "reasoning": "AI response parsing fallback"
+            }
+        except Exception as e:
+            return {
+                "verdict": "On Track",
+                "message": f"Error analyzing activity: {str(e)}",
+                "reasoning": "Error occurred"
+            }
+
+    def analyze(self, active_task: Optional[Dict], recent_activity: List[Dict]) -> Dict:
+        """Analyze current activity and return verdict."""
+        if not active_task:
+            return {
+                "verdict": "Idle",
+                "message": "No active task selected. Pick a task to get started! 🎯",
+                "reasoning": "No active task",
+                "timestamp": datetime.now().isoformat()
+            }
+
+        if not self.connection_healthy or not self.client:
+            provider_name = self.provider.upper()
+            if self.provider == "vllm":
+                msg = f"⚠️ vLLM server not reachable. Make sure it's running at {self.base_url}"
+            else:
+                msg = f"⚠️ {provider_name} API key not configured. Add your API key to enable AI monitoring."
+            return {
+                "verdict": "On Track",
+                "message": msg,
+                "reasoning": "No connection",
+                "timestamp": datetime.now().isoformat()
+            }
+
+        prompt = self._create_analysis_prompt(active_task, recent_activity)
+        result = self._call_llm(prompt)
+        result["timestamp"] = datetime.now().isoformat()
+
+        # Track consecutive idle/distracted states
+        verdict = result.get("verdict", "On Track")
+        if verdict == "Idle":
+            self.idle_count += 1
+            self.distracted_count = 0
+        elif verdict == "Distracted":
+            self.distracted_count += 1
+            self.idle_count = 0
+        else:
+            self.idle_count = 0
+            self.distracted_count = 0
+
+        result["should_alert"] = (self.idle_count >= 2 or self.distracted_count >= 2)
+        self.last_verdict = verdict
+
+        return result
+
+    def get_onboarding_tasks(self, project_description: str) -> List[Dict]:
+        """Generate micro-tasks from project description."""
+        if not self.connection_healthy or not self.client:
+            return []
+
+        prompt = f"""You are FocusFlow, an AI project planner.
+
+The user wants to build: "{project_description}"
+
+Break this down into 5-8 concrete, actionable micro-tasks. Each task should be:
+- Specific and achievable in 15-30 minutes
+- Ordered logically (setup → core features → polish)
+- Clearly described
+
+Respond in JSON format:
+{{
+  "tasks": [
+    {{"title": "Task 1 title", "description": "Detailed description", "estimated_duration": "15 min"}},
+    {{"title": "Task 2 title", "description": "Detailed description", "estimated_duration": "20 min"}}
+  ]
+}}"""
+
+        try:
+            if self.provider in ["openai", "vllm"]:
+                if not self.client:
+                    return []
+                response = self.client.chat.completions.create(
+                    model=self.model,
+                    messages=[{"role": "user", "content": prompt}],
+                    temperature=0.7,
+                    max_tokens=800
+                )
+                content = response.choices[0].message.content
+            elif self.provider == "gemini":
+                if not self.client:
+                    return []
+                response = self.client.generate_content(
+                    prompt,
+                    generation_config={
+                        "temperature": 0.7,
+                        "max_output_tokens": 800,
+                    }
+                )
+                content = response.text
+            else:  # anthropic
+                if not self.client:
+                    return []
+                response = self.client.messages.create(
+                    model=self.model,
+                    max_tokens=800,
+                    temperature=0.7,
+                    messages=[{"role": "user", "content": prompt}]
+                )
+                content = response.content[0].text
+
+            if not content:
+                return []
+
+            # Parse JSON
+            content = content.strip()
+            if "```json" in content:
+                content = content.split("```json")[1].split("```")[0].strip()
+            elif "```" in content:
+                content = content.split("```")[1].split("```")[0].strip()
+
+            result = json.loads(content)
+            return result.get("tasks", [])
+
+        except Exception as e:
+            print(f"Error generating tasks: {e}")
+            return []
+
+
+class MockFocusAgent(FocusAgent):
+    """Mock agent for demo mode without API keys. Returns predefined responses."""
+
+    def __init__(self):
+        """Initialize mock agent without any API dependencies."""
+        self.provider = "mock"
+        self.last_verdict = None
+        self.idle_count = 0
+        self.distracted_count = 0
+        self.connection_healthy = True
+        self.client = None
+        self.api_key = None
+        self.check_counter = 0
+
+        self.verdicts_cycle = ["On Track", "On Track", "Distracted", "On Track", "Idle"]
+        self.messages = {
+            "On Track": [
+                "Great work! You're making solid progress! 🎯",
+                "Keep it up! I see you're focused on the task. 💪",
+                "Looking good! You're on the right track! ✨",
+                "Nice! Your workflow is looking productive! 🚀"
+            ],
+            "Distracted": [
+                "Wait, what are you working on? That doesn't look like the task! 🤨",
+                "Hmm, spotted some wandering there. Let's refocus! 👀",
+                "Getting a bit sidetracked? Back to the task! 🎯",
+                "I see you there! Time to get back on track! 🦉"
+            ],
+            "Idle": [
+                "Files won't write themselves. *Hoot hoot.* 🦉",
+                "Hey! Time to make some progress! ⏰",
+                "No activity detected. Let's get moving! 💤",
+                "Your task is waiting! Let's code! 🔥"
+            ]
+        }
+
+    def analyze(self, active_task: Optional[Dict], recent_activity: List[Dict]) -> Dict:
+        """Return mock analysis results."""
+        if not active_task:
+            return {
+                "verdict": "Idle",
+                "message": "No active task selected. Pick a task to get started! 🎯",
+                "reasoning": "No active task (mock mode)",
+                "timestamp": datetime.now().isoformat()
+            }
+
+        # Cycle through verdicts
+        verdict = self.verdicts_cycle[self.check_counter % len(self.verdicts_cycle)]
+        self.check_counter += 1
+
+        # Get message for this verdict
+        import random
+        message = random.choice(self.messages[verdict])
+
+        # Track consecutive states
+        if verdict == "Idle":
+            self.idle_count += 1
+            self.distracted_count = 0
+        elif verdict == "Distracted":
+            self.distracted_count += 1
+            self.idle_count = 0
+        else:
+            self.idle_count = 0
+            self.distracted_count = 0
+
+        self.last_verdict = verdict
+
+        return {
+            "verdict": verdict,
+            "message": message,
+            "reasoning": f"Mock analysis for task: {active_task.get('title', 'Unknown')}",
+            "timestamp": datetime.now().isoformat(),
+            "should_alert": (self.idle_count >= 2 or self.distracted_count >= 2)
+        }
+
+    def get_onboarding_tasks(self, project_description: str) -> List[Dict]:
+        """Generate mock tasks based on project description."""
+        # Simple keyword-based task generation
+        description_lower = project_description.lower()
+
+        if any(word in description_lower for word in ["web", "website", "app", "frontend"]):
+            return [
+                {"title": "Set up project structure", "description": "Create folders and initial files", "estimated_duration": "15 min"},
+                {"title": "Design UI mockup", "description": "Sketch out the main interface", "estimated_duration": "20 min"},
+                {"title": "Build homepage", "description": "Create the landing page HTML/CSS", "estimated_duration": "30 min"},
+                {"title": "Add navigation", "description": "Implement menu and routing", "estimated_duration": "25 min"},
+                {"title": "Connect backend", "description": "Set up API integration", "estimated_duration": "30 min"},
+                {"title": "Test and debug", "description": "Fix bugs and test functionality", "estimated_duration": "20 min"}
+            ]
+        elif any(word in description_lower for word in ["api", "backend", "server"]):
+            return [
+                {"title": "Set up project structure", "description": "Initialize project and dependencies", "estimated_duration": "15 min"},
+                {"title": "Design database schema", "description": "Plan data models and relationships", "estimated_duration": "20 min"},
+                {"title": "Create API endpoints", "description": "Build REST routes", "estimated_duration": "30 min"},
+                {"title": "Add authentication", "description": "Implement user auth", "estimated_duration": "25 min"},
+                {"title": "Write tests", "description": "Create unit and integration tests", "estimated_duration": "30 min"}
+            ]
+        else:
+            # Generic tasks
+            return [
+                {"title": "Research and planning", "description": "Gather requirements and plan approach", "estimated_duration": "20 min"},
+                {"title": "Set up environment", "description": "Install dependencies and tools", "estimated_duration": "15 min"},
+                {"title": "Build core feature #1", "description": "Implement main functionality", "estimated_duration": "30 min"},
+                {"title": "Build core feature #2", "description": "Add secondary features", "estimated_duration": "25 min"},
+                {"title": "Testing and debugging", "description": "Test and fix issues", "estimated_duration": "20 min"},
+                {"title": "Documentation", "description": "Write README and comments", "estimated_duration": "15 min"}
+            ]

app.py

@@ -1,70 +1,61 @@
-import gradio as gr
-from huggingface_hub import InferenceClient
-
-
-def respond(
-    message,
-    history: list[dict[str, str]],
-    system_message,
-    max_tokens,
-    temperature,
-    top_p,
-    hf_token: gr.OAuthToken,
-):
-    """
-    For more information on `huggingface_hub` Inference API support, please check the docs: https://huggingface.co/docs/huggingface_hub/v0.22.2/en/guides/inference
-    """
-    client = InferenceClient(token=hf_token.token, model="openai/gpt-oss-20b")
-
-    messages = [{"role": "system", "content": system_message}]
-
-    messages.extend(history)
-
-    messages.append({"role": "user", "content": message})
-
-    response = ""
-
-    for message in client.chat_completion(
-        messages,
-        max_tokens=max_tokens,
-        stream=True,
-        temperature=temperature,
-        top_p=top_p,
-    ):
-        choices = message.choices
-        token = ""
-        if len(choices) and choices[0].delta.content:
-            token = choices[0].delta.content
-
-        response += token
-        yield response
-
-
 """
-For information on how to customize the ChatInterface, peruse the gradio docs: https://www.gradio.app/docs/chatinterface
+FocusFlow: AI Accountability Agent with Gradio 5 Interface.
+Configurable via environment variables for HuggingFace Spaces or local use.
 """
-chatbot = gr.ChatInterface(
-    respond,
-    type="messages",
-    additional_inputs=[
-        gr.Textbox(value="You are a friendly Chatbot.", label="System message"),
-        gr.Slider(minimum=1, maximum=2048, value=512, step=1, label="Max new tokens"),
-        gr.Slider(minimum=0.1, maximum=4.0, value=0.7, step=0.1, label="Temperature"),
-        gr.Slider(
-            minimum=0.1,
-            maximum=1.0,
-            value=0.95,
-            step=0.05,
-            label="Top-p (nucleus sampling)",
-        ),
-    ],
-)
-
-with gr.Blocks() as demo:
-    with gr.Sidebar():
-        gr.LoginButton()
-    chatbot.render()
-
+import gradio as gr
+import os
+from dotenv import load_dotenv
+from storage import TaskManager
+from monitor import FileMonitor
+from metrics import MetricsTracker
+from voice import voice_generator
+from linear_client import LinearClient
+from core.pomodoro import PomodoroTimer
+from core.focus_check import FocusMonitor
+from ui.handlers import UIHandlers
+from ui.layout import create_app
+
+# Load environment variables
+load_dotenv()
+
+# Import MCP tools to register them with Gradio
+try:
+    import mcp_tools
+    MCP_AVAILABLE = True
+except Exception as e:
+    print(f"⚠️ MCP tools not available: {e}")
+    MCP_AVAILABLE = False
+
+# Configuration from environment
+LAUNCH_MODE = os.getenv("LAUNCH_MODE", "demo").lower()  # 'demo' or 'local'
+AI_PROVIDER = os.getenv("AI_PROVIDER", "openai").lower()  # 'openai', 'anthropic', or 'vllm'
+MONITOR_INTERVAL = int(os.getenv("MONITOR_INTERVAL", "30"))  # seconds
+
+# Initialize Core Components
+task_manager = TaskManager()
+file_monitor = FileMonitor()
+metrics_tracker = MetricsTracker()
+linear_client = LinearClient()
+
+# Initialize Logic Modules
+focus_monitor = FocusMonitor(task_manager, file_monitor, metrics_tracker, voice_generator)
+focus_monitor.set_launch_mode(LAUNCH_MODE)
+
+pomodoro_timer = PomodoroTimer()
+
+# Initialize UI Handlers
+ui_handlers = UIHandlers(task_manager, file_monitor, metrics_tracker, focus_monitor, linear_client)
+
+# Create App
+app = create_app(ui_handlers, pomodoro_timer, LAUNCH_MODE, AI_PROVIDER, MONITOR_INTERVAL)
 
 if __name__ == "__main__":
-    demo.launch()
+    # Enable MCP server if available
+    mcp_enabled = os.getenv("ENABLE_MCP", "true").lower() == "true"
+
+    if MCP_AVAILABLE and mcp_enabled:
+        print("🔗 MCP Server enabled! Connect via Claude Desktop or other MCP clients.")
+        app.launch(server_name="0.0.0.0", server_port=5000, share=False, mcp_server=True)
+    else:
+        print("📱 Running without MCP integration")
+        app.launch(server_name="0.0.0.0", server_port=5000, share=False)

core/focus_check.py

@@ -0,0 +1,143 @@
+"""
+Focus Monitoring Logic.
+"""
+import time
+import json
+from typing import List, Optional, Tuple, Any
+
+class FocusMonitor:
+    def __init__(self, task_manager, file_monitor, metrics_tracker, voice_generator=None):
+        self.task_manager = task_manager
+        self.file_monitor = file_monitor
+        self.metrics_tracker = metrics_tracker
+        self.voice_generator = voice_generator
+
+        self.focus_agent = None
+        self.consecutive_distracted = 0
+        self.activity_log: List[str] = []
+        self.demo_text_content = ""
+        self.launch_mode = "demo" # Default
+
+    def set_agent(self, agent):
+        self.focus_agent = agent
+
+    def set_launch_mode(self, mode: str):
+        self.launch_mode = mode
+
+    def update_demo_text(self, text: str) -> str:
+        """Update demo text content (demo mode only)."""
+        self.demo_text_content = text
+        return f"✅ Text updated ({len(text)} characters)"
+
+    def get_activity_summary(self, monitoring_active: bool) -> str:
+        """Get recent activity summary."""
+        if self.launch_mode == "demo":
+            return f"📝 Demo text content: {len(self.demo_text_content)} characters"
+
+        if not monitoring_active:
+            return "⏸️ Monitoring is not active"
+
+        recent = self.file_monitor.get_recent_activity(5)
+        if not recent:
+            return "💤 No recent file activity"
+
+        summary = []
+        for event in recent:
+            summary.append(f"• {event['type'].upper()}: {event['filename']}")
+
+        return "\n".join(summary)
+
+    def run_check(self) -> Tuple[str, Optional[str], Optional[Any]]:
+        """
+        Run the focus check analysis with distraction escalation.
+        Returns:
+            Tuple[log_string, alert_js, voice_audio]
+        """
+        if not self.focus_agent:
+            return "⚠️ Agent not initialized. Check environment variables.", None, None
+
+        active_task = self.task_manager.get_active_task()
+
+        # Get recent activity based on mode
+        if self.launch_mode == "demo":
+            # In demo mode, create synthetic activity from text content
+            recent_activity = [{
+                'type': 'text_edit',
+                'filename': 'demo_workspace',
+                'content': self.demo_text_content[-500:] if self.demo_text_content else "",
+                'timestamp': time.time()
+            }] if self.demo_text_content else []
+        else:
+            recent_activity = self.file_monitor.get_recent_activity(10)
+
+        result = self.focus_agent.analyze(active_task, recent_activity)
+
+        verdict = result.get("verdict", "Unknown")
+        message = result.get("message", "No message")
+
+        # Handle distraction escalation logic
+        if verdict == "On Track":
+            # Reset counter when back on track
+            self.consecutive_distracted = 0
+        elif verdict == "Distracted":
+            # Increment distraction counter
+            self.consecutive_distracted += 1
+
+        # Log to metrics if we have an active task
+        if active_task:
+            self.metrics_tracker.log_focus_check(
+                active_task['id'],
+                active_task['title'],
+                verdict,
+                message
+            )
+
+        # Determine emoji
+        emoji = "✅" if verdict == "On Track" else "⚠️" if verdict == "Distracted" else "💤"
+
+        log_entry = f"{emoji} [{verdict}] {message}"
+        self.activity_log.append(log_entry)
+
+        # Keep only last 20 entries
+        if len(self.activity_log) > 20:
+            self.activity_log.pop(0)
+
+        # Generate voice feedback (optional, graceful if unavailable)
+        voice_audio = None
+        if self.voice_generator:
+            try:
+                voice_audio = self.voice_generator.get_focus_message_audio(verdict, message)
+            except Exception as e:
+                print(f"Voice generation error: {e}")
+
+        # Trigger browser alert and audio for distracted/idle status with escalation
+        alert_js = None
+        if verdict in ["Distracted", "Idle"]:
+            safe_message = json.dumps(message)
+
+            # Escalation logic:
+            # 1st distraction: play sound only
+            # 2nd distraction: play sound again
+            # 3rd+ distraction: add voice feedback
+            # play_voice = self.consecutive_distracted >= 3 # Logic handled by caller or voice_audio presence?
+            # Actually voice_audio is generated regardless, but maybe we only play it if distracted?
+            # The original code generated it always if available.
+
+            alert_js = f"""
+            () => {{
+                const audio = document.getElementById('nudge-alert');
+                if (audio) {{
+                    audio.currentTime = 0;
+                    audio.play().catch(e => console.log('Audio play failed:', e));
+                }}
+                if (Notification.permission === "granted") {{
+                    new Notification("FocusFlow Alert 🦉", {{
+                        body: {safe_message},
+                        icon: "https://em-content.zobj.net/thumbs/160/apple/354/owl_1f989.png"
+                    }});
+                }}
+                return null;
+            }}
+            """
+
+        return "\n".join(self.activity_log), alert_js, voice_audio

core/pomodoro.py

@@ -0,0 +1,70 @@
+"""
+Pomodoro Timer Logic for FocusFlow.
+"""
+from typing import Dict, Tuple
+
+class PomodoroTimer:
+    def __init__(self):
+        self.state = {
+            "minutes": 25,
+            "seconds": 0,
+            "is_running": False,
+            "is_work_time": True,
+            "total_seconds": 25 * 60
+        }
+
+    def format_time(self, total_seconds: int) -> str:
+        """Format seconds to MM:SS format."""
+        mins = total_seconds // 60
+        secs = total_seconds % 60
+        return f"{mins:02d}:{secs:02d}"
+
+    def get_display(self) -> str:
+        """Get current Pomodoro display string."""
+        time_str = self.format_time(self.state["total_seconds"])
+        status_str = "Work Time ⏰" if self.state["is_work_time"] else "Break Time ☕"
+        running_indicator = " (Running)" if self.state["is_running"] else ""
+        return f"**{time_str}** {status_str}{running_indicator}"
+
+    def start(self) -> str:
+        """Start the Pomodoro timer."""
+        self.state["is_running"] = True
+        return f"▶️ Timer started! {self.get_display()}"
+
+    def pause(self) -> str:
+        """Pause the Pomodoro timer."""
+        self.state["is_running"] = False
+        return f"⏸️ Timer paused. {self.get_display()}"
+
+    def reset(self) -> str:
+        """Reset the Pomodoro timer."""
+        self.state["is_running"] = False
+        self.state["total_seconds"] = 25 * 60
+        self.state["minutes"] = 25
+        self.state["seconds"] = 0
+        self.state["is_work_time"] = True
+        return f"🔄 Timer reset. {self.get_display()}"
+
+    def tick(self) -> Tuple[str, bool]:
+        """
+        Tick the Pomodoro timer.
+        Returns:
+            Tuple[display_string, should_play_sound]
+        """
+        if not self.state["is_running"]:
+            return self.get_display(), False
+
+        # Decrement timer
+        self.state["total_seconds"] -= 1
+
+        should_play_sound = False
+
+        # Check if session complete
+        if self.state["total_seconds"] <= 0:
+            # Switch between work and break
+            self.state["is_work_time"] = not self.state["is_work_time"]
+            self.state["total_seconds"] = (25 * 60) if self.state["is_work_time"] else (5 * 60)
+            self.state["is_running"] = False  # Auto-pause to get attention
+            should_play_sound = True
+
+        return self.get_display(), should_play_sound

linear_client.py

@@ -0,0 +1,141 @@
+"""
+Linear Client for FocusFlow.
+Handles integration with Linear API (or MCP server) for task synchronization.
+Falls back to mock data if no API key is provided.
+"""
+import os
+import json
+import requests
+from typing import List, Dict, Optional
+from datetime import datetime
+
+class LinearClient:
+    """Client for interacting with Linear."""
+
+    def __init__(self, api_key: Optional[str] = None):
+        """Initialize Linear client."""
+        self.api_key = api_key or os.getenv("LINEAR_API_KEY")
+        self.api_url = "https://api.linear.app/graphql"
+        self.is_active = bool(self.api_key)
+
+        if not self.is_active:
+            print("ℹ️ Linear: No API key found. Using mock data.")
+
+    def _headers(self) -> Dict[str, str]:
+        """Get request headers."""
+        return {
+            "Content-Type": "application/json",
+            "Authorization": self.api_key
+        }
+
+    def _query(self, query: str, variables: Dict = None) -> Dict:
+        """Execute GraphQL query."""
+        if not self.is_active:
+            return {}
+
+        try:
+            response = requests.post(
+                self.api_url,
+                headers=self._headers(),
+                json={"query": query, "variables": variables or {}}
+            )
+            response.raise_for_status()
+            return response.json()
+        except Exception as e:
+            print(f"⚠️ Linear API error: {e}")
+            return {}
+
+    def get_user_projects(self) -> List[Dict]:
+        """Get projects for the current user."""
+        if not self.is_active:
+            return [
+                {"id": "mock-1", "name": "Website Redesign", "description": "Overhaul the company website"},
+                {"id": "mock-2", "name": "Mobile App", "description": "iOS and Android app development"},
+                {"id": "mock-3", "name": "API Migration", "description": "Migrate legacy API to GraphQL"}
+            ]
+
+        query = """
+        query {
+            viewer {
+                projects(first: 10) {
+                    nodes {
+                        id
+                        name
+                        description
+                    }
+                }
+            }
+        }
+        """
+        result = self._query(query)
+        try:
+            return result.get("data", {}).get("viewer", {}).get("projects", {}).get("nodes", [])
+        except Exception:
+            return []
+
+    def get_project_tasks(self, project_id: str) -> List[Dict]:
+        """Get tasks for a specific project."""
+        if not self.is_active:
+            # Return mock tasks based on project ID
+            if project_id == "mock-1":
+                return [
+                    {"id": "L-101", "title": "Design Homepage", "description": "Create Figma mockups", "estimate": 60},
+                    {"id": "L-102", "title": "Implement Header", "description": "React component for header", "estimate": 30},
+                    {"id": "L-103", "title": "Fix CSS Bugs", "description": "Fix mobile layout issues", "estimate": 45}
+                ]
+            return [
+                {"id": "L-201", "title": "Setup Repo", "description": "Initialize git repository", "estimate": 15},
+                {"id": "L-202", "title": "Basic Auth", "description": "Implement login flow", "estimate": 60}
+            ]
+
+        query = """
+        query($projectId: ID!) {
+            project(id: $projectId) {
+                issues(first: 20, filter: { state: { name: { neq: "Done" } } }) {
+                    nodes {
+                        id
+                        title
+                        description
+                        estimate
+                    }
+                }
+            }
+        }
+        """
+        result = self._query(query, {"projectId": project_id})
+        try:
+            return result.get("data", {}).get("project", {}).get("issues", {}).get("nodes", [])
+        except Exception:
+            return []
+
+    def create_task(self, title: str, description: str = "", team_id: str = None) -> Optional[str]:
+        """Create a new task (issue) in Linear."""
+        if not self.is_active:
+            print(f"ℹ️ Linear (Mock): Created task '{title}'")
+            return "mock-new-id"
+
+        # Note: This requires a team_id. For simplicity, we might need to fetch a default team first.
+        # This is a simplified implementation.
+        if not team_id:
+            # Try to get the first team
+            team_query = """query { viewer { teams(first: 1) { nodes { id } } } }"""
+            team_res = self._query(team_query)
+            try:
+                team_id = team_res["data"]["viewer"]["teams"]["nodes"][0]["id"]
+            except:
+                return None
+
+        mutation = """
+        mutation($title: String!, $description: String, $teamId: String!) {
+            issueCreate(input: { title: $title, description: $description, teamId: $teamId }) {
+                issue {
+                    id
+                }
+            }
+        }
+        """
+        result = self._query(mutation, {"title": title, "description": description, "teamId": team_id})
+        try:
+            return result["data"]["issueCreate"]["issue"]["id"]
+        except:
+            return None

mcp_tools.py

@@ -0,0 +1,261 @@
+"""
+MCP (Model Context Protocol) tools and resources for FocusFlow.
+Enables LLM assistants like Claude Desktop to interact with FocusFlow.
+"""
+import gradio as gr
+from typing import Dict, List, Optional
+from storage import TaskManager
+from metrics import MetricsTracker
+
+# Initialize shared instances for MCP tools
+# Note: These are separate from app.py's instances but use the same database
+task_manager = TaskManager()
+metrics_tracker = MetricsTracker()
+
+
+@gr.mcp.tool()
+def add_task(title: str, description: str = "", duration: int = 30) -> str:
+    """
+    Create a new task in FocusFlow.
+
+    Args:
+        title: Task title (required)
+        description: Detailed task description (optional)
+        duration: Estimated duration in minutes (default: 30)
+
+    Returns:
+        Success message with task ID
+    """
+    try:
+        duration_str = f"{duration} min"
+        task_id = task_manager.add_task(title, description, duration_str, status="Todo")
+        return f"✅ Task created successfully! ID: {task_id}, Title: '{title}', Duration: {duration} min"
+    except Exception as e:
+        return f"❌ Error creating task: {str(e)}"
+
+
+@gr.mcp.tool()
+def get_current_task() -> str:
+    """
+    Get the currently active task (marked as 'In Progress').
+
+    Returns:
+        Details of the active task or message if no active task
+    """
+    try:
+        active_task = task_manager.get_active_task()
+        if not active_task:
+            return "ℹ️ No active task. Use start_task(task_id) to begin working on a task."
+
+        return f"""📋 Current Active Task:
+- ID: {active_task['id']}
+- Title: {active_task['title']}
+- Description: {active_task.get('description', 'No description')}
+- Duration: {active_task.get('estimated_duration', 'Not specified')}
+- Status: {active_task['status']}"""
+    except Exception as e:
+        return f"❌ Error getting current task: {str(e)}"
+
+
+@gr.mcp.tool()
+def start_task(task_id: int) -> str:
+    """
+    Mark a task as 'In Progress' and set it as the active task.
+    Only one task can be active at a time.
+
+    Args:
+        task_id: ID of the task to start
+
+    Returns:
+        Success or error message
+    """
+    try:
+        # Check if task exists first
+        task = task_manager.get_task(task_id)
+        if not task:
+            return f"❌ Task {task_id} not found. Use get_all_tasks() to see available tasks."
+
+        success = task_manager.set_active_task(task_id)
+        if success:
+            return f"✅ Task {task_id} started: '{task['title']}'. FocusFlow is now monitoring your progress!"
+        else:
+            return f"❌ Failed to start task {task_id}. Task is already marked as Done."
+    except Exception as e:
+        return f"❌ Error starting task: {str(e)}"
+
+
+@gr.mcp.tool()
+def mark_task_done(task_id: int) -> str:
+    """
+    Mark a task as completed ('Done').
+
+    Args:
+        task_id: ID of the task to complete
+
+    Returns:
+        Success or error message
+    """
+    try:
+        # Check if task exists first
+        task = task_manager.get_task(task_id)
+        if not task:
+            return f"❌ Task {task_id} not found. Use get_all_tasks() to see available tasks."
+
+        task_manager.update_task(task_id, status="Done")
+        return f"🎉 Task {task_id} completed: '{task['title']}'! Great work!"
+    except Exception as e:
+        return f"❌ Error marking task done: {str(e)}"
+
+
+@gr.mcp.tool()
+def get_all_tasks() -> str:
+    """
+    Get a list of all tasks with their current status.
+
+    Returns:
+        Formatted list of all tasks
+    """
+    try:
+        tasks = task_manager.get_all_tasks()
+        if not tasks:
+            return "📝 No tasks yet. Use add_task() to create your first task!"
+
+        result = f"📋 All Tasks ({len(tasks)} total):\n\n"
+        for task in tasks:
+            status_emoji = "✅" if task['status'] == "Done" else "🔄" if task['status'] == "In Progress" else "⏳"
+            result += f"{status_emoji} [{task['id']}] {task['title']}\n"
+            if task.get('description'):
+                result += f"   Description: {task['description']}\n"
+            result += f"   Status: {task['status']} | Duration: {task.get('estimated_duration', 'N/A')}\n\n"
+
+        return result.strip()
+    except Exception as e:
+        return f"❌ Error getting tasks: {str(e)}"
+
+
+@gr.mcp.tool()
+def delete_task(task_id: int) -> str:
+    """
+    Delete a task permanently.
+
+    Args:
+        task_id: ID of the task to delete
+
+    Returns:
+        Success or error message
+    """
+    try:
+        task = task_manager.get_task(task_id)
+        if not task:
+            return f"❌ Task {task_id} not found."
+
+        title = task['title']
+        task_manager.delete_task(task_id)
+        return f"🗑️ Task {task_id} deleted: '{title}'"
+    except Exception as e:
+        return f"❌ Error deleting task: {str(e)}"
+
+
+@gr.mcp.tool()
+def update_task(task_id: int, title: Optional[str] = None, description: Optional[str] = None,
+                status: Optional[str] = None, duration: Optional[int] = None) -> str:
+    """
+    Update an existing task.
+
+    Args:
+        task_id: ID of the task to update
+        title: New title (optional)
+        description: New description (optional)
+        status: New status (Todo, In Progress, Done) (optional)
+        duration: New estimated duration in minutes (optional)
+
+    Returns:
+        Success or error message
+    """
+    try:
+        task = task_manager.get_task(task_id)
+        if not task:
+            return f"❌ Task {task_id} not found."
+
+        updates = {}
+        if title is not None:
+            updates['title'] = title
+        if description is not None:
+            updates['description'] = description
+        if status is not None:
+            updates['status'] = status
+        if duration is not None:
+            updates['estimated_duration'] = f"{duration} min"
+
+        if not updates:
+            return "ℹ️ No changes provided."
+
+        task_manager.update_task(task_id, **updates)
+        return f"✅ Task {task_id} updated successfully!"
+    except Exception as e:
+        return f"❌ Error updating task: {str(e)}"
+
+
+@gr.mcp.tool()
+def get_productivity_stats() -> str:
+    """
+    Get productivity statistics and insights including focus metrics.
+
+    Returns:
+        Summary of task completion, progress, and focus scores
+    """
+    try:
+        # Task statistics
+        tasks = task_manager.get_all_tasks()
+        if not tasks:
+            return "📊 No tasks to analyze yet. Create some tasks to see your productivity stats!"
+
+        total = len(tasks)
+        completed = sum(1 for t in tasks if t['status'] == 'Done')
+        in_progress = sum(1 for t in tasks if t['status'] == 'In Progress')
+        todo = sum(1 for t in tasks if t['status'] == 'Todo')
+
+        completion_rate = (completed / total * 100) if total > 0 else 0
+
+        # Focus metrics
+        today_stats = metrics_tracker.get_today_stats()
+        current_streak = metrics_tracker.get_current_streak()
+
+        result = f"""📊 Productivity Statistics:
+
+📋 Task Progress:
+✅ Completed: {completed}/{total} tasks ({completion_rate:.1f}%)
+🔄 In Progress: {in_progress} task(s)
+⏳ To Do: {todo} tasks
+
+🎯 Focus Metrics (Today):
+⭐ Focus Score: {today_stats['focus_score']}/100
+🔥 Current Streak: {current_streak} consecutive "On Track" checks
+📊 Total Checks: {today_stats['total_checks']}
+  • On Track: {today_stats['on_track']}
+  • Distracted: {today_stats['distracted']}
+  • Idle: {today_stats['idle']}
+
+Keep up the good work! 🎯"""
+        return result
+    except Exception as e:
+        return f"❌ Error getting stats: {str(e)}"
+
+
+# MCP Resources
+@gr.mcp.resource("focusflow://tasks/all")
+def get_all_tasks_resource() -> str:
+    """Expose all tasks as an MCP resource."""
+    return get_all_tasks()
+
+
+@gr.mcp.resource("focusflow://tasks/active")
+def get_active_task_resource() -> str:
+    """Expose the active task as an MCP resource."""
+    return get_current_task()
+
+
+@gr.mcp.resource("focusflow://stats")
+def get_stats_resource() -> str:
+    """Expose productivity statistics as an MCP resource."""
+    return get_productivity_stats()

metrics.py

@@ -0,0 +1,247 @@
+"""
+Productivity metrics tracking for FocusFlow.
+Tracks focus scores, completion rates, and streaks.
+"""
+import sqlite3
+from datetime import datetime, timedelta
+from typing import Dict, List, Tuple
+import json
+
+
+class MetricsTracker:
+    """Tracks productivity metrics and focus history."""
+    
+    def __init__(self, db_path: str = "focusflow.db"):
+        """Initialize metrics tracker with SQLite database."""
+        self.db_path = db_path
+        self._init_db()
+    
+    def _init_db(self):
+        """Create metrics tables if they don't exist."""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        
+        # Focus check history
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS focus_history (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                task_id INTEGER,
+                task_title TEXT,
+                verdict TEXT,
+                message TEXT,
+                timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+        
+        # Daily streaks
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS streaks (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                date DATE UNIQUE,
+                on_track_count INTEGER DEFAULT 0,
+                distracted_count INTEGER DEFAULT 0,
+                idle_count INTEGER DEFAULT 0,
+                max_consecutive_on_track INTEGER DEFAULT 0,
+                focus_score REAL DEFAULT 0
+            )
+        """)
+        
+        conn.commit()
+        conn.close()
+    
+    def log_focus_check(self, task_id: int, task_title: str, verdict: str, message: str):
+        """Log a focus check result."""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        
+        cursor.execute("""
+            INSERT INTO focus_history (task_id, task_title, verdict, message, timestamp)
+            VALUES (?, ?, ?, ?, ?)
+        """, (task_id, task_title, verdict, message, datetime.now()))
+        
+        # Update today's streak data
+        today = datetime.now().date()
+        
+        # Get or create today's streak record
+        cursor.execute("SELECT * FROM streaks WHERE date = ?", (today,))
+        row = cursor.fetchone()
+        
+        if row:
+            # Update existing record
+            on_track = row[2] + (1 if verdict == "On Track" else 0)
+            distracted = row[3] + (1 if verdict == "Distracted" else 0)
+            idle = row[4] + (1 if verdict == "Idle" else 0)
+            
+            # Calculate consecutive on-track streak
+            cursor.execute("""
+                SELECT verdict FROM focus_history 
+                WHERE DATE(timestamp) = ? 
+                ORDER BY timestamp DESC LIMIT 20
+            """, (today,))
+            recent_verdicts = [r[0] for r in cursor.fetchall()]
+            recent_verdicts.reverse()
+            
+            consecutive = 0
+            for v in reversed(recent_verdicts):
+                if v == "On Track":
+                    consecutive += 1
+                else:
+                    break
+            
+            max_consecutive = max(row[5], consecutive)
+            
+            # Calculate focus score (0-100)
+            total_checks = on_track + distracted + idle
+            focus_score = (on_track / total_checks * 100) if total_checks > 0 else 0
+            
+            cursor.execute("""
+                UPDATE streaks 
+                SET on_track_count = ?, distracted_count = ?, idle_count = ?, 
+                    max_consecutive_on_track = ?, focus_score = ?
+                WHERE date = ?
+            """, (on_track, distracted, idle, max_consecutive, focus_score, today))
+        else:
+            # Create new record
+            on_track = 1 if verdict == "On Track" else 0
+            distracted = 1 if verdict == "Distracted" else 0
+            idle = 1 if verdict == "Idle" else 0
+            focus_score = (on_track / 1 * 100) if (on_track + distracted + idle) > 0 else 0
+            
+            cursor.execute("""
+                INSERT INTO streaks (date, on_track_count, distracted_count, idle_count, 
+                                    max_consecutive_on_track, focus_score)
+                VALUES (?, ?, ?, ?, ?, ?)
+            """, (today, on_track, distracted, idle, on_track, focus_score))
+        
+        conn.commit()
+        conn.close()
+    
+    def get_today_stats(self) -> Dict:
+        """Get today's productivity statistics."""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        
+        today = datetime.now().date()
+        cursor.execute("SELECT * FROM streaks WHERE date = ?", (today,))
+        row = cursor.fetchone()
+        
+        conn.close()
+        
+        if not row:
+            return {
+                "on_track": 0,
+                "distracted": 0,
+                "idle": 0,
+                "max_streak": 0,
+                "focus_score": 0,
+                "total_checks": 0
+            }
+        
+        return {
+            "on_track": row[2],
+            "distracted": row[3],
+            "idle": row[4],
+            "max_streak": row[5],
+            "focus_score": round(row[6], 1),
+            "total_checks": row[2] + row[3] + row[4]
+        }
+    
+    def get_weekly_stats(self) -> List[Dict]:
+        """Get last 7 days of statistics."""
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        cursor = conn.cursor()
+        
+        seven_days_ago = datetime.now().date() - timedelta(days=6)
+        
+        cursor.execute("""
+            SELECT date, on_track_count, distracted_count, idle_count, focus_score
+            FROM streaks
+            WHERE date >= ?
+            ORDER BY date DESC
+        """, (seven_days_ago,))
+        
+        rows = cursor.fetchall()
+        conn.close()
+        
+        return [dict(row) for row in rows]
+    
+    def get_focus_history(self, limit: int = 20) -> List[Dict]:
+        """Get recent focus check history."""
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        cursor = conn.cursor()
+        
+        cursor.execute("""
+            SELECT task_title, verdict, message, timestamp
+            FROM focus_history
+            ORDER BY timestamp DESC
+            LIMIT ?
+        """, (limit,))
+        
+        rows = cursor.fetchall()
+        conn.close()
+        
+        return [dict(row) for row in rows]
+    
+    def get_current_streak(self) -> int:
+        """Get current consecutive 'On Track' streak."""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        
+        today = datetime.now().date()
+        cursor.execute("""
+            SELECT verdict FROM focus_history 
+            WHERE DATE(timestamp) = ? 
+            ORDER BY timestamp DESC LIMIT 50
+        """, (today,))
+        
+        verdicts = [r[0] for r in cursor.fetchall()]
+        conn.close()
+        
+        streak = 0
+        for verdict in verdicts:
+            if verdict == "On Track":
+                streak += 1
+            else:
+                break
+        
+        return streak
+    
+    def get_chart_data(self) -> Dict:
+        """Get data formatted for charts."""
+        weekly = self.get_weekly_stats()
+        
+        # Prepare data for charts
+        dates = []
+        focus_scores = []
+        on_track_counts = []
+        distracted_counts = []
+        idle_counts = []
+        
+        # Fill in missing days with zeros
+        for i in range(7):
+            date = datetime.now().date() - timedelta(days=6-i)
+            dates.append(date.strftime("%m/%d"))
+            
+            # Find matching data
+            day_data = next((d for d in weekly if str(d['date']) == str(date)), None)
+            
+            if day_data:
+                focus_scores.append(day_data['focus_score'])
+                on_track_counts.append(day_data['on_track_count'])
+                distracted_counts.append(day_data['distracted_count'])
+                idle_counts.append(day_data['idle_count'])
+            else:
+                focus_scores.append(0)
+                on_track_counts.append(0)
+                distracted_counts.append(0)
+                idle_counts.append(0)
+        
+        return {
+            "dates": dates,
+            "focus_scores": focus_scores,
+            "on_track": on_track_counts,
+            "distracted": distracted_counts,
+            "idle": idle_counts
+        }

monitor.py

@@ -0,0 +1,171 @@
+"""
+File monitoring using watchdog with content-aware diff detection.
+"""
+import os
+import time
+from pathlib import Path
+from typing import List, Dict, Optional, Callable
+from watchdog.observers import Observer
+from watchdog.events import FileSystemEventHandler, FileSystemEvent
+from datetime import datetime
+import threading
+
+
+class ContentAwareHandler(FileSystemEventHandler):
+    """Handler that tracks file changes with content awareness."""
+    
+    IGNORED_PATTERNS = [
+        '.git', '__pycache__', '.env', 'node_modules', 
+        '.venv', 'venv', '.idea', '.vscode',
+        '.pyc', '.pyo', '.pyd', '.so', '.dll', '.dylib'
+    ]
+    
+    TEXT_EXTENSIONS = [
+        '.py', '.js', '.jsx', '.ts', '.tsx', '.html', '.css', 
+        '.json', '.md', '.txt', '.yaml', '.yml', '.toml',
+        '.c', '.cpp', '.h', '.java', '.go', '.rs', '.rb'
+    ]
+    
+    def __init__(self, callback: Optional[Callable] = None):
+        """Initialize the handler with optional callback."""
+        super().__init__()
+        self.events: List[Dict] = []
+        self.callback = callback
+        self.last_event_time = {}
+        self.debounce_seconds = 1.0
+    
+    def _should_ignore(self, path: str) -> bool:
+        """Check if path should be ignored."""
+        path_parts = Path(path).parts
+        for pattern in self.IGNORED_PATTERNS:
+            if pattern in path_parts or path.endswith(pattern):
+                return True
+        return False
+    
+    def _is_text_file(self, path: str) -> bool:
+        """Check if file is a text file we should read."""
+        return any(path.endswith(ext) for ext in self.TEXT_EXTENSIONS)
+    
+    def _read_file_content(self, path: str, max_chars: int = 500) -> str:
+        """Read last N characters of a text file."""
+        try:
+            if not os.path.exists(path) or not os.path.isfile(path):
+                return ""
+            
+            if not self._is_text_file(path):
+                return "[Binary file]"
+            
+            with open(path, 'r', encoding='utf-8', errors='ignore') as f:
+                content = f.read()
+                if len(content) > max_chars:
+                    return f"...{content[-max_chars:]}"
+                return content
+        except Exception as e:
+            return f"[Error reading file: {str(e)}]"
+    
+    def _debounce_event(self, path: str) -> bool:
+        """Check if event should be debounced (too soon after last event)."""
+        now = time.time()
+        last_time = self.last_event_time.get(path, 0)
+        
+        if now - last_time < self.debounce_seconds:
+            return True
+        
+        self.last_event_time[path] = now
+        return False
+    
+    def _create_event(self, event_type: str, path: str):
+        """Create and store an event."""
+        if self._should_ignore(path):
+            return
+        
+        if self._debounce_event(path):
+            return
+        
+        event_data = {
+            'type': event_type,
+            'path': path,
+            'filename': os.path.basename(path),
+            'timestamp': datetime.now().isoformat(),
+            'content': self._read_file_content(path) if event_type == 'modified' else ""
+        }
+        
+        self.events.append(event_data)
+        
+        # Keep only last 50 events
+        if len(self.events) > 50:
+            self.events = self.events[-50:]
+        
+        if self.callback:
+            self.callback(event_data)
+    
+    def on_modified(self, event: FileSystemEvent):
+        """Handle file modification."""
+        if not event.is_directory:
+            self._create_event('modified', str(event.src_path))
+    
+    def on_created(self, event: FileSystemEvent):
+        """Handle file creation."""
+        if not event.is_directory:
+            self._create_event('created', str(event.src_path))
+    
+    def on_deleted(self, event: FileSystemEvent):
+        """Handle file deletion."""
+        if not event.is_directory:
+            self._create_event('deleted', str(event.src_path))
+    
+    def get_recent_events(self, limit: int = 10) -> List[Dict]:
+        """Get the most recent events."""
+        return self.events[-limit:]
+    
+    def clear_events(self):
+        """Clear all stored events."""
+        self.events = []
+
+
+class FileMonitor:
+    """File monitor using watchdog."""
+    
+    def __init__(self):
+        """Initialize the file monitor."""
+        self.observer = None
+        self.handler = None
+        self.watching_path = None
+    
+    def start(self, path: str, callback: Optional[Callable] = None):
+        """Start monitoring a directory."""
+        if self.observer and self.observer.is_alive():
+            self.stop()
+        
+        if not os.path.exists(path):
+            raise ValueError(f"Path does not exist: {path}")
+        
+        self.watching_path = path
+        self.handler = ContentAwareHandler(callback)
+        self.observer = Observer()
+        self.observer.schedule(self.handler, path, recursive=True)
+        self.observer.start()
+    
+    def stop(self):
+        """Stop monitoring."""
+        if self.observer and self.observer.is_alive():
+            self.observer.stop()
+            self.observer.join(timeout=2)
+        self.observer = None
+        self.handler = None
+        self.watching_path = None
+    
+    def get_recent_activity(self, limit: int = 10) -> List[Dict]:
+        """Get recent file activity."""
+        if self.handler:
+            return self.handler.get_recent_events(limit)
+        return []
+    
+    def clear_activity(self):
+        """Clear activity log."""
+        if self.handler:
+            self.handler.clear_events()
+    
+    def is_running(self) -> bool:
+        """Check if monitor is running."""
+        return self.observer is not None and self.observer.is_alive()

requirements.txt

@@ -0,0 +1,13 @@
+gradio>=5.0.0
+gradio[mcp]
+openai>=1.0.0
+anthropic>=0.34.0
+google-generativeai>=0.8.0
+watchdog>=3.0.0
+python-dotenv>=1.0.0
+# vllm>=0.6.0
+elevenlabs>=1.0.0
+linear>=0.1.0
+requests>=2.31.0
+pytest
+sseclient-py

storage.py

@@ -0,0 +1,198 @@
+"""
+Task Manager with SQLite backend for CRUD operations.
+"""
+import sqlite3
+import json
+from typing import List, Dict, Optional
+from datetime import datetime
+import os
+
+
+class TaskManager:
+    """Manages tasks with SQLite persistence."""
+    
+    # Strict status enum
+    VALID_STATUSES = {"Todo", "In Progress", "Done"}
+    
+    def __init__(self, db_path: str = "focusflow.db"):
+        """Initialize the task manager with SQLite database."""
+        self.db_path = db_path
+        self._init_db()
+    
+    def _init_db(self):
+        """Create the tasks table if it doesn't exist."""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS tasks (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                title TEXT NOT NULL,
+                description TEXT,
+                status TEXT DEFAULT 'Todo',
+                estimated_duration TEXT,
+                position INTEGER,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            )
+        """)
+        conn.commit()
+        conn.close()
+    
+    def add_task(self, title: str, description: str = "", 
+                 estimated_duration: str = "", status: str = "Todo") -> int:
+        """Add a new task and return its ID."""
+        # Validate status
+        if status not in self.VALID_STATUSES:
+            status = "Todo"
+        
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        
+        # Get max position
+        cursor.execute("SELECT MAX(position) FROM tasks")
+        max_pos = cursor.fetchone()[0]
+        position = (max_pos or 0) + 1
+        
+        cursor.execute("""
+            INSERT INTO tasks (title, description, status, estimated_duration, position)
+            VALUES (?, ?, ?, ?, ?)
+        """, (title, description, status, estimated_duration, position))
+        
+        task_id = cursor.lastrowid or 0
+        conn.commit()
+        conn.close()
+        return task_id
+    
+    def get_all_tasks(self) -> List[Dict]:
+        """Get all tasks ordered by position."""
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        cursor = conn.cursor()
+        
+        cursor.execute("""
+            SELECT id, title, description, status, estimated_duration, position
+            FROM tasks ORDER BY position
+        """)
+        
+        tasks = [dict(row) for row in cursor.fetchall()]
+        conn.close()
+        return tasks
+    
+    def get_task(self, task_id: int) -> Optional[Dict]:
+        """Get a specific task by ID."""
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        cursor = conn.cursor()
+        
+        cursor.execute("""
+            SELECT id, title, description, status, estimated_duration, position
+            FROM tasks WHERE id = ?
+        """, (task_id,))
+        
+        row = cursor.fetchone()
+        conn.close()
+        return dict(row) if row else None
+    
+    def update_task(self, task_id: int, **kwargs):
+        """Update a task's fields with validation."""
+        # Validate status if provided
+        if 'status' in kwargs and kwargs['status'] not in self.VALID_STATUSES:
+            raise ValueError(f"Invalid status. Must be one of: {', '.join(self.VALID_STATUSES)}")
+        
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        
+        allowed_fields = ['title', 'description', 'status', 'estimated_duration', 'position']
+        updates = []
+        values = []
+        
+        for key, value in kwargs.items():
+            if key in allowed_fields:
+                updates.append(f"{key} = ?")
+                values.append(value)
+        
+        if updates:
+            values.append(task_id)
+            query = f"UPDATE tasks SET {', '.join(updates)}, updated_at = CURRENT_TIMESTAMP WHERE id = ?"
+            cursor.execute(query, values)
+            conn.commit()
+        
+        conn.close()
+    
+    def delete_task(self, task_id: int):
+        """Delete a task by ID."""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute("DELETE FROM tasks WHERE id = ?", (task_id,))
+        conn.commit()
+        conn.close()
+    
+    def reorder_tasks(self, task_ids: List[int]):
+        """Reorder tasks based on new order."""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        
+        for position, task_id in enumerate(task_ids, start=1):
+            cursor.execute("UPDATE tasks SET position = ? WHERE id = ?", (position, task_id))
+        
+        conn.commit()
+        conn.close()
+    
+    def get_active_task(self) -> Optional[Dict]:
+        """Get the task marked as 'In Progress'."""
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        cursor = conn.cursor()
+        
+        cursor.execute("""
+            SELECT id, title, description, status, estimated_duration
+            FROM tasks WHERE status = 'In Progress'
+            ORDER BY position LIMIT 1
+        """)
+        
+        row = cursor.fetchone()
+        conn.close()
+        return dict(row) if row else None
+    
+    def set_active_task(self, task_id: int) -> bool:
+        """Set a task as 'In Progress' and ensure only one task has this status.
+        Returns True if successful, False otherwise."""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        
+        # Check if task exists and is not already Done
+        cursor.execute("SELECT status FROM tasks WHERE id = ?", (task_id,))
+        result = cursor.fetchone()
+        
+        if not result:
+            conn.close()
+            return False
+        
+        current_status = result[0]
+        if current_status == "Done":
+            conn.close()
+            return False
+        
+        # Enforce single "In Progress" rule: set all current "In Progress" tasks back to "Todo"
+        cursor.execute("""
+            UPDATE tasks SET status = 'Todo', updated_at = CURRENT_TIMESTAMP
+            WHERE status = 'In Progress'
+        """)
+        
+        # Set the selected task as 'In Progress'
+        cursor.execute("""
+            UPDATE tasks SET status = 'In Progress', updated_at = CURRENT_TIMESTAMP
+            WHERE id = ?
+        """, (task_id,))
+        
+        conn.commit()
+        conn.close()
+        return True
+    
+    def clear_all_tasks(self):
+        """Clear all tasks from the database."""
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute("DELETE FROM tasks")
+        conn.commit()
+        conn.close()

ui/handlers.py

@@ -0,0 +1,307 @@
+"""
+UI Event Handlers for FocusFlow.
+"""
+import os
+import gradio as gr
+import pandas as pd
+from agent import FocusAgent, MockFocusAgent
+
+class UIHandlers:
+    def __init__(self, task_manager, file_monitor, metrics_tracker, focus_monitor, linear_client=None):
+        self.task_manager = task_manager
+        self.file_monitor = file_monitor
+        self.metrics_tracker = metrics_tracker
+        self.focus_monitor = focus_monitor
+        self.linear_client = linear_client
+
+        # State
+        self.monitoring_active = False
+        self.timer_active = False
+        self.check_interval = 30 # Default
+
+    def get_voice_status_ui(self) -> str:
+        """Get voice integration status for UI display."""
+        from voice import get_voice_status
+        return get_voice_status()
+
+    def initialize_agent(self, ai_provider: str) -> tuple:
+        """
+        Initialize the AI agent.
+        Returns: (status_message, actual_provider_display)
+        """
+        try:
+            use_mock = False
+            focus_agent = None
+
+            if ai_provider == "anthropic":
+                api_key = os.getenv("DEMO_ANTHROPIC_API_KEY") or os.getenv("ANTHROPIC_API_KEY")
+                if not api_key:
+                    use_mock = True
+                else:
+                    try:
+                        focus_agent = FocusAgent(provider="anthropic", api_key=api_key)
+                        key_type = "demo" if os.getenv("DEMO_ANTHROPIC_API_KEY") else "user"
+                        self.focus_monitor.set_agent(focus_agent)
+                        return (f"✅ Anthropic Claude initialized successfully ({key_type} key)",
+                               f"**AI Provider:** `ANTHROPIC (Claude)`")
+                    except Exception as e:
+                        print(f"⚠️ Anthropic API error: {e}")
+                        use_mock = True
+
+            elif ai_provider == "openai":
+                api_key = os.getenv("DEMO_OPENAI_API_KEY") or os.getenv("OPENAI_API_KEY")
+                if not api_key:
+                    use_mock = True
+                else:
+                    try:
+                        focus_agent = FocusAgent(provider="openai", api_key=api_key)
+                        key_type = "demo" if os.getenv("DEMO_OPENAI_API_KEY") else "user"
+                        self.focus_monitor.set_agent(focus_agent)
+                        return (f"✅ OpenAI GPT-4 initialized successfully ({key_type} key)",
+                               f"**AI Provider:** `OPENAI (GPT-4o)`")
+                    except Exception as e:
+                        print(f"⚠️ OpenAI API error: {e}")
+                        use_mock = True
+
+            elif ai_provider == "gemini":
+                api_key = os.getenv("DEMO_GEMINI_API_KEY") or os.getenv("GEMINI_API_KEY")
+                if not api_key:
+                    use_mock = True
+                else:
+                    try:
+                        focus_agent = FocusAgent(provider="gemini", api_key=api_key)
+                        key_type = "demo" if os.getenv("DEMO_GEMINI_API_KEY") else "user"
+                        self.focus_monitor.set_agent(focus_agent)
+                        return (f"✅ Google Gemini initialized successfully ({key_type} key)",
+                               f"**AI Provider:** `GEMINI (Flash 2.0)`")
+                    except Exception as e:
+                        print(f"⚠️ Gemini API error: {e}")
+                        use_mock = True
+
+            elif ai_provider == "vllm":
+                try:
+                    focus_agent = FocusAgent(
+                        provider="vllm",
+                        api_key=os.getenv("VLLM_API_KEY", "EMPTY"),
+                        base_url=os.getenv("VLLM_BASE_URL", "http://localhost:8000/v1"),
+                        model=os.getenv("VLLM_MODEL", "ibm-granite/granite-4.0-h-1b")
+                    )
+                    if not focus_agent.connection_healthy:
+                        use_mock = True
+                    else:
+                        self.focus_monitor.set_agent(focus_agent)
+                        return (f"✅ vLLM initialized successfully!",
+                               f"**AI Provider:** `VLLM (Local)`")
+                except Exception as e:
+                    print(f"⚠️ vLLM error: {e}")
+                    use_mock = True
+
+            # Use mock agent if no API keys or connections available
+            if use_mock:
+                focus_agent = MockFocusAgent()
+                self.focus_monitor.set_agent(focus_agent)
+                return (f"ℹ️ Running in DEMO MODE with Mock AI (no API keys needed). Perfect for testing! 🎭",
+                       f"**AI Provider:** `MOCK AI (Demo Mode)`")
+
+            # Fallback
+            focus_agent = MockFocusAgent()
+            self.focus_monitor.set_agent(focus_agent)
+            return (f"ℹ️ Using Mock AI for demo",
+                   f"**AI Provider:** `MOCK AI (Fallback)`")
+
+        except Exception as e:
+            focus_agent = MockFocusAgent()
+            self.focus_monitor.set_agent(focus_agent)
+            return (f"ℹ️ Using Mock AI for demo (Error: {str(e)}) 🎭",
+                   f"**AI Provider:** `MOCK AI (Error Fallback)`")
+
+    def process_onboarding(self, project_description: str) -> tuple:
+        """Process onboarding and generate tasks."""
+        if not self.focus_monitor.focus_agent:
+            return "❌ Please initialize agent first", self.get_task_dataframe(), 0
+
+        if not project_description.strip():
+            return "❌ Please describe your project", self.get_task_dataframe(), 0
+
+        # Generate tasks
+        tasks = self.focus_monitor.focus_agent.get_onboarding_tasks(project_description)
+
+        if not tasks:
+            return "❌ Failed to generate tasks. Check your AI provider configuration.", self.get_task_dataframe(), 0
+
+        # Add tasks to database
+        self.task_manager.clear_all_tasks()
+        for task in tasks:
+            self.task_manager.add_task(
+                title=task.get("title", "Untitled"),
+                description=task.get("description", ""),
+                estimated_duration=task.get("estimated_duration", "30 min")
+            )
+
+        return f"✅ Generated {len(tasks)} tasks! Go to Task Manager to start.", self.get_task_dataframe(), self.calculate_progress()
+
+    def get_task_dataframe(self):
+        """Get tasks as a list for display."""
+        tasks = self.task_manager.get_all_tasks()
+        if not tasks:
+            return []
+
+        display_tasks = []
+        for task in tasks:
+            display_tasks.append([
+                task['id'],
+                task['title'],
+                task['description'],
+                task['status'],
+                task['estimated_duration']
+            ])
+        return display_tasks
+
+    def calculate_progress(self) -> float:
+        """Calculate overall task completion percentage."""
+        tasks = self.task_manager.get_all_tasks()
+        if not tasks:
+            return 0.0
+
+        completed = sum(1 for task in tasks if task['status'] == "Done")
+        return (completed / len(tasks)) * 100
+
+    def add_new_task(self, title: str, description: str, duration: int, status: str) -> tuple:
+        """Add a new task."""
+        if not title.strip():
+            return "", "", 30, "Todo", self.get_task_dataframe(), self.calculate_progress()
+
+        duration_str = f"{duration} min"
+        self.task_manager.add_task(title, description, duration_str, status)
+        return "", "", 30, "Todo", self.get_task_dataframe(), self.calculate_progress()
+
+    def delete_task(self, task_id: str) -> tuple:
+        """Delete a task by ID."""
+        try:
+            self.task_manager.delete_task(int(task_id))
+            return "✅ Task deleted", self.get_task_dataframe(), self.calculate_progress()
+        except Exception as e:
+            return f"❌ Error: {str(e)}", self.get_task_dataframe(), self.calculate_progress()
+
+    def set_task_active(self, task_id: str) -> tuple:
+        """Set a task as active."""
+        try:
+            self.task_manager.set_active_task(int(task_id))
+            return "✅ Task set as active! Start working and I'll monitor your progress.", self.get_task_dataframe(), self.calculate_progress()
+        except Exception as e:
+            return f"❌ Error: {str(e)}", self.get_task_dataframe(), self.calculate_progress()
+
+    def mark_task_done(self, task_id: str) -> tuple:
+        """Mark a task as completed."""
+        try:
+            self.task_manager.update_task(int(task_id), status="Done")
+            return "✅ Task marked as completed! 🎉", self.get_task_dataframe(), self.calculate_progress()
+        except Exception as e:
+            return f"❌ Error: {str(e)}", self.get_task_dataframe(), self.calculate_progress()
+
+    def start_monitoring(self, watch_path: str, launch_mode: str) -> tuple:
+        """Start file monitoring."""
+        if launch_mode == "demo":
+            return "❌ File monitoring disabled in demo mode. Use the text area instead.", gr.update(active=False)
+
+        if not watch_path or not os.path.exists(watch_path):
+            self.monitoring_active = False
+            self.timer_active = False
+            return f"❌ Invalid path: {watch_path}", gr.update(active=False)
+
+        try:
+            self.file_monitor.start(watch_path)
+            self.monitoring_active = True
+            self.timer_active = True
+            return f"✅ Monitoring started on: {watch_path}", gr.update(active=True)
+        except Exception as e:
+            self.monitoring_active = False
+            self.timer_active = False
+            return f"❌ Error: {str(e)}", gr.update(active=False)
+
+    def stop_monitoring(self) -> tuple:
+        """Stop file monitoring."""
+        self.file_monitor.stop()
+        self.monitoring_active = False
+        self.timer_active = False
+        return "⏹️ Monitoring stopped", gr.update(active=False)
+
+    def set_check_interval(self, frequency_label: str) -> tuple:
+        """Update check interval based on dropdown selection."""
+        frequency_map = {
+            "30 seconds": 30,
+            "1 minute": 60,
+            "5 minutes": 300,
+            "10 minutes": 600,
+        }
+
+        self.check_interval = frequency_map.get(frequency_label, 30)
+        # Return updated timer component
+        return (
+            gr.Timer(value=self.check_interval, active=self.timer_active),
+            f"✅ Check interval set to {frequency_label}"
+        )
+
+    def refresh_dashboard(self) -> tuple:
+        """Refresh dashboard with latest metrics."""
+        today_stats = self.metrics_tracker.get_today_stats()
+        current_streak = self.metrics_tracker.get_current_streak()
+
+        state_data = pd.DataFrame([
+            {"state": "On Track", "count": today_stats["on_track"]},
+            {"state": "Distracted", "count": today_stats["distracted"]},
+            {"state": "Idle", "count": today_stats["idle"]}
+        ])
+
+        chart_data = self.metrics_tracker.get_chart_data()
+        weekly_data = pd.DataFrame({
+            "date": chart_data["dates"],
+            "score": chart_data["focus_scores"]
+        })
+
+        return (
+            today_stats["focus_score"],
+            current_streak,
+            today_stats["total_checks"],
+            state_data,
+            weekly_data
+        )
+
+    # Linear Integration
+    def get_linear_projects_ui(self):
+        """Get Linear projects for dropdown."""
+        if not self.linear_client:
+             return gr.update(choices=[], value=None, visible=True), "⚠️ Linear client not initialized"
+
+        projects = self.linear_client.get_user_projects()
+        if not projects:
+            return gr.update(choices=[], value=None, visible=True), "⚠️ No projects found (or API key missing)"
+
+        choices = [(p['name'], p['id']) for p in projects]
+        return gr.update(choices=choices, value=choices[0][1] if choices else None, visible=True), f"✅ Found {len(projects)} projects"
+
+    def import_linear_tasks_ui(self, project_id):
+        """Import tasks from selected Linear project."""
+        if not self.linear_client:
+             return "⚠️ Linear client not initialized", self.get_task_dataframe(), self.calculate_progress()
+
+        if not project_id:
+            return "❌ Select a project first", self.get_task_dataframe(), self.calculate_progress()
+
+        tasks = self.linear_client.get_project_tasks(project_id)
+        if not tasks:
+            return "⚠️ No open tasks found in this project", self.get_task_dataframe(), self.calculate_progress()
+
+        count = 0
+        for t in tasks:
+            estimate = t.get('estimate', 30) or 30
+            duration_str = f"{estimate} min"
+            self.task_manager.add_task(
+                title=t['title'],
+                description=t.get('description', ''),
+                estimated_duration=duration_str,
+                status="Todo"
+            )
+            count += 1
+
+        return f"✅ Imported {count} tasks from Linear!", self.get_task_dataframe(), self.calculate_progress()

ui/layout.py

@@ -0,0 +1,528 @@
+"""
+Gradio Layout for FocusFlow.
+"""
+import gradio as gr
+import os
+import inspect
+from core.pomodoro import PomodoroTimer
+import mcp_tools
+
+def register_tool_safely(func):
+    """Register a tool with correct signature by creating dummy components."""
+    sig = inspect.signature(func)
+    inputs = []
+    for name, param in sig.parameters.items():
+        # Map types to components
+        if param.annotation == int:
+            inputs.append(gr.Number(label=name, visible=False))
+        elif param.annotation == bool:
+            inputs.append(gr.Checkbox(label=name, visible=False))
+        else:
+            inputs.append(gr.Textbox(label=name, visible=False))
+
+    # Dummy output to capture return value
+    output = gr.Textbox(visible=False)
+
+    # Hidden button to trigger
+    btn = gr.Button(f"cmd_{func.__name__}", visible=False)
+    btn.click(fn=func, inputs=inputs, outputs=[output])
+
+def create_app(ui_handlers, pomodoro_timer: PomodoroTimer, launch_mode: str, ai_provider: str, monitor_interval: int):
+    """Create the Gradio Blocks app."""
+
+    with gr.Blocks(title="FocusFlow AI") as app:
+
+        # MCP Tools Registration (Hidden)
+        with gr.Row(visible=False):
+            # Register all tools from mcp_tools
+            register_tool_safely(mcp_tools.add_task)
+            register_tool_safely(mcp_tools.get_current_task)
+            register_tool_safely(mcp_tools.start_task)
+            register_tool_safely(mcp_tools.mark_task_done)
+            register_tool_safely(mcp_tools.get_all_tasks)
+            register_tool_safely(mcp_tools.delete_task)
+            register_tool_safely(mcp_tools.update_task)
+            register_tool_safely(mcp_tools.get_productivity_stats)
+
+        # Hidden component for browser alerts
+        alert_trigger = gr.HTML(visible=False)
+
+        # Auto-refresh timer for monitoring (default 30s)
+        monitor_timer = gr.Timer(value=monitor_interval, active=False)
+
+        # Dedicated 1-second timer for Pomodoro
+        pomodoro_ticker = gr.Timer(value=1, active=True)
+
+        with gr.Tabs() as tabs:
+            # Tab 1: Home/Landing Page
+            with gr.Tab("🏠 Home"):
+                gr.Markdown("""
+                # 🦉 FocusFlow - Your AI Accountability Buddy
+
+                Keep focused on your coding tasks with Duolingo-style nudges!
+                """)
+
+                # Status indicators
+                init_status = gr.Textbox(label="AI Status", value="Initializing...", interactive=False, scale=1)
+                voice_status_display = gr.Textbox(label="Voice Status", value="Checking...", interactive=False, scale=1)
+
+                gr.Markdown("""
+                ## ✨ Features
+
+                - **🎯 AI-Powered Project Planning**: Break down projects into actionable micro-tasks
+                - **📊 Progress Tracking**: Visual progress monitoring with completion percentages
+                - **👁️ Real-Time Monitoring**: Track your coding activity and stay focused
+                - **🦉 Duolingo-Style Nudges**: Encouraging, sassy, and gentle reminders
+                - **🔔 Browser Notifications**: Get alerted when you're distracted
+                - **🚀 Multi-Provider AI**: OpenAI, Anthropic, or local vLLM support
+                - **🔊 Voice Feedback**: ElevenLabs voice alerts for maximum engagement
+
+                ## ⚙️ Current Configuration
+                """)
+
+                # Dynamic AI provider display
+                ai_provider_display = gr.Markdown(f"**AI Provider:** `{ai_provider.upper()}`")
+
+                with gr.Row():
+                    gr.Markdown(f"**Mode:** `{launch_mode.upper()}`")
+                    ai_provider_display
+                    gr.Markdown(f"**Check Interval:** `{monitor_interval}s`")
+
+                if launch_mode == "demo":
+                    gr.Markdown("""
+                    > ℹ️ **Demo Mode**: Use the text area in Monitor tab to simulate your workspace.
+                    """)
+                else:
+                    gr.Markdown("""
+                    > ℹ️ **Local Mode**: Monitor your actual project directory.
+                    """)
+
+                gr.Markdown("""
+                ---
+                **Get Started:** Navigate to Onboarding → describe your project → manage tasks → start monitoring!
+                """)
+
+            # Tab 2: Onboarding
+            with gr.Tab("🚀 Onboarding"):
+                gr.Markdown("""
+                ## AI-Powered Project Planning
+
+                Describe your project and I'll break it down into actionable micro-tasks!
+                """)
+
+                project_input = gr.Textbox(
+                    label="What are you building?",
+                    placeholder="e.g., 'A Python web scraper that extracts product data from e-commerce sites'",
+                    lines=5
+                )
+                generate_btn = gr.Button("✨ Generate Tasks", variant="primary", size="lg")
+                onboard_status = gr.Markdown("")
+
+                # Linear Integration
+                gr.Markdown("""
+                ---
+                ## 🔗 Import from Linear
+                Connect to your Linear workspace to import existing issues.
+                """)
+
+                with gr.Row():
+                    refresh_projects_btn = gr.Button("🔄 Load Projects", size="sm", scale=1)
+                    project_selector = gr.Dropdown(label="Select Project", choices=[], scale=3, interactive=True)
+                    import_linear_btn = gr.Button("⬇️ Import Tasks", variant="secondary", scale=1)
+
+            # Tab 3: Task Manager
+            with gr.Tab("📋 Tasks"):
+                gr.Markdown("## 📋 Your Tasks")
+
+                # Compact header: Progress bar + Action buttons in one row
+                with gr.Row():
+                    progress_bar = gr.Slider(
+                        label="Overall Progress",
+                        value=0,
+                        minimum=0,
+                        maximum=100,
+                        interactive=False,
+                        scale=3
+                    )
+                    with gr.Column(scale=1, min_width=250):
+                        gr.Markdown("**Quick Actions:**")
+                        with gr.Row():
+                            start_task_btn = gr.Button("▶️ Start", size="sm", variant="secondary", scale=1)
+                            mark_done_btn = gr.Button("✅ Done", size="sm", variant="secondary", scale=1)
+                            delete_task_btn = gr.Button("🗑️ Delete", size="sm", variant="stop", scale=1)
+
+                # State to hold selected task ID
+                selected_task_id = gr.State(value=None)
+
+                # Table view
+                gr.Markdown("**Click on a task row to edit it, or add a new task:**")
+                task_table = gr.Dataframe(
+                    headers=["ID", "Title", "Description", "Status", "Duration (min)"],
+                    value=[],
+                    interactive=False,
+                    wrap=True
+                )
+
+                selection_info = gr.Markdown("_Click **+ Add Task** to create a new task, or click a row above to edit._")
+
+                # Button to show Add form
+                add_task_trigger_btn = gr.Button("➕ Add Task", variant="primary", size="sm")
+
+                # Single dynamic form (hidden by default)
+                with gr.Column(visible=False, elem_id="task-form-container") as task_form:
+                    form_header = gr.Markdown("### ✏️ Task Form")
+                    form_title = gr.Textbox(label="Title", placeholder="Task title")
+                    form_desc = gr.Textbox(label="Description", placeholder="Describe the task", lines=2)
+                    with gr.Row():
+                        form_duration = gr.Number(label="Duration (minutes)", value=30, minimum=5, maximum=480, step=5, scale=2)
+                        form_status = gr.Dropdown(
+                            label="Status",
+                            choices=["Todo", "In Progress", "Done"],
+                            value="Todo",
+                            scale=1
+                        )
+                    with gr.Row():
+                        form_save_btn = gr.Button("💾 Save", variant="primary", size="sm", scale=1)
+                        form_cancel_btn = gr.Button("❌ Cancel", variant="secondary", size="sm", scale=1)
+
+            # Tab 4: Dashboard
+            with gr.Tab("📊 Dashboard"):
+                gr.Markdown("## 📊 Productivity Dashboard")
+
+                # Today's stats
+                with gr.Row():
+                    with gr.Column(scale=1):
+                        today_focus_score = gr.Number(label="Focus Score", value=0, interactive=False)
+                    with gr.Column(scale=1):
+                        today_streak = gr.Number(label="Current Streak 🔥", value=0, interactive=False)
+                    with gr.Column(scale=1):
+                        today_checks = gr.Number(label="Total Checks", value=0, interactive=False)
+
+                # State distribution (today)
+                gr.Markdown("### Today's Focus Distribution")
+                import pandas as pd
+                empty_state_df = pd.DataFrame([{"state": "On Track", "count": 0}, {"state": "Distracted", "count": 0}, {"state": "Idle", "count": 0}])
+                state_plot = gr.BarPlot(
+                    value=empty_state_df,
+                    x="state",
+                    y="count",
+                    title="Focus States Distribution"
+                )
+
+                # Weekly focus score trend
+                gr.Markdown("### Weekly Focus Score Trend")
+                empty_weekly_df = pd.DataFrame({"date": [], "score": []})
+                weekly_plot = gr.LinePlot(
+                    value=empty_weekly_df,
+                    x="date",
+                    y="score",
+                    title="Focus Score (Last 7 Days)"
+                )
+
+                refresh_dashboard_btn = gr.Button("🔄 Refresh Dashboard", variant="secondary")
+
+            # Tab 5: Monitor
+            with gr.Tab("👁️ Monitor"):
+                gr.Markdown("## Focus Monitoring")
+
+                # Mode-specific UI
+                if launch_mode == "demo":
+                    gr.Markdown("**Demo Workspace** - Edit the text below to simulate coding:")
+                    demo_textarea = gr.Textbox(
+                        label="Your Code",
+                        placeholder="Type or paste your code here...",
+                        lines=8,
+                        value="# Welcome to FocusFlow!\n# Start coding..."
+                    )
+                    demo_update_btn = gr.Button("💾 Save Changes", variant="secondary")
+                    demo_status = gr.Textbox(label="Status", interactive=False)
+                    watch_path_input = gr.State(value=None) # Dummy
+                    start_monitor_btn = gr.State(value=None) # Dummy
+                    stop_monitor_btn = gr.State(value=None) # Dummy
+                    monitor_status = gr.State(value=None) # Dummy
+                else:
+                    gr.Markdown("**Directory Monitoring**")
+                    watch_path_input = gr.Textbox(
+                        label="Path to Monitor",
+                        value=os.getcwd(),
+                        placeholder="/path/to/your/project"
+                    )
+                    with gr.Row():
+                        start_monitor_btn = gr.Button("▶️ Start", variant="primary", size="sm")
+                        stop_monitor_btn = gr.Button("⏹️ Stop", variant="stop", size="sm")
+                    monitor_status = gr.Textbox(label="Status", interactive=False)
+                    demo_textarea = gr.State(value=None) # Dummy
+                    demo_update_btn = gr.State(value=None) # Dummy
+                    demo_status = gr.State(value=None) # Dummy
+
+                # Check frequency selector
+                gr.Markdown("### ⚙️ Monitoring Settings")
+                check_frequency = gr.Dropdown(
+                    label="Check Frequency",
+                    choices=["30 seconds", "1 minute", "5 minutes", "10 minutes"],
+                    value="30 seconds",
+                    interactive=True
+                )
+
+                check_frequency.change(
+                    fn=ui_handlers.set_check_interval,
+                    inputs=[check_frequency],
+                    outputs=[monitor_timer, monitor_status if launch_mode != "demo" else demo_status],
+                    api_name=False
+                )
+
+                # Pomodoro Timer
+                gr.Markdown("### 🍅 Pomodoro Timer")
+
+                # Timer display with embedded audio alerts
+                with gr.Row():
+                    pomodoro_display = gr.Markdown(value=pomodoro_timer.get_display(), elem_id="pomodoro-display")
+                    gr.HTML("""
+                    <audio id="pomodoro-alert" preload="auto">
+                        <source src="data:audio/wav;base64,UklGRnoGAABXQVZFZm10IBAAAAABAAEAQB8AAEAfAAABAAgAZGF0YQoGAACBhYqFbF1fdJivrJBhNjVgodDbq2EcBj+a2/LDciUFLIHO8tiJNwgZaLvt559NEAxQp+PwtmMcBjiR1/LMeSwFJHfH8N2QQAoUXrTp66hVFApGn+DyvmwhBSuBzvLZiTUI" type="audio/wav">
+                    </audio>
+                    <audio id="nudge-alert" preload="auto">
+                        <source src="data:audio/wav;base64,UklGRnoGAABXQVZFZm10IBAAAAABAAEAQB8AAEAfAAABAAgAZGF0YQoGAACBhYqFbF1fdJivrJBhNjVgodDbq2EcBj+a2/LDciUFLIHO8tiJNwgZaLvt559NEAxQp+PwtmMcBjiR1/LMeSwFJHfH8N2QQAoUXrTp66hVFApGn+DyvmwhBSuBzvLZiTUI" type="audio/wav">
+                    </audio>
+                    """)
+
+                with gr.Row():
+                    pomodoro_start_btn = gr.Button("▶️ Start", size="sm", scale=1)
+                    pomodoro_stop_btn = gr.Button("⏸️ Pause", size="sm", scale=1)
+                    pomodoro_reset_btn = gr.Button("🔄 Reset", size="sm", scale=1)
+
+                # Focus log (common for both modes)
+                gr.Markdown("### 🦉 Focus Agent Log")
+                focus_log = gr.Textbox(
+                    label="Activity Log",
+                    lines=8,
+                    interactive=False,
+                    placeholder="Focus checks will appear here..."
+                )
+
+                # Voice feedback player
+                voice_audio = gr.Audio(
+                    label="🔊 Voice Feedback",
+                    visible=True,
+                    autoplay=True,
+                    show_label=True,
+                    elem_id="voice-feedback-player"
+                )
+
+                with gr.Row():
+                    manual_check_btn = gr.Button("🔍 Run Focus Check Now", variant="secondary")
+                    if launch_mode == "demo":
+                        timer_toggle_btn = gr.Button("⏸️ Pause Auto-Check", variant="secondary")
+                    else:
+                        timer_toggle_btn = gr.Button("▶️ Start Auto-Check", variant="secondary")
+
+        # --- Event Handlers ---
+
+        # Initialization
+        app.load(fn=lambda: ui_handlers.initialize_agent(ai_provider), outputs=[init_status, ai_provider_display], api_name=False)
+        app.load(fn=ui_handlers.get_voice_status_ui, outputs=voice_status_display, api_name=False)
+
+        # Onboarding
+        generate_btn.click(
+            fn=ui_handlers.process_onboarding,
+            inputs=[project_input],
+            outputs=[onboard_status, task_table, progress_bar],
+            api_name=False
+        )
+
+        # Linear Integration
+        refresh_projects_btn.click(
+            fn=ui_handlers.get_linear_projects_ui,
+            outputs=[project_selector, onboard_status],
+            api_name=False
+        )
+        import_linear_btn.click(
+            fn=ui_handlers.import_linear_tasks_ui,
+            inputs=[project_selector],
+            outputs=[onboard_status, task_table, progress_bar],
+            api_name=False
+        )
+
+        # Task Management
+        add_task_trigger_btn.click(
+            fn=lambda: gr.update(visible=True),
+            outputs=task_form,
+            api_name=False
+        )
+        form_cancel_btn.click(
+            fn=lambda: gr.update(visible=False),
+            outputs=task_form,
+            api_name=False
+        )
+        form_save_btn.click(
+            fn=ui_handlers.add_new_task,
+            inputs=[form_title, form_desc, form_duration, form_status],
+            outputs=[form_title, form_desc, form_duration, form_status, task_table, progress_bar],
+            api_name=False
+        )
+        form_save_btn.click(
+            fn=lambda: gr.update(visible=False),
+            outputs=task_form,
+            api_name=False
+        )
+
+        # Task Selection Handler
+        def on_select_task(evt: gr.SelectData, data):
+            try:
+                # data is a pandas DataFrame
+                row_index = evt.index[0]
+                task_id = data.iloc[row_index][0] # ID is in first column
+                return task_id, f"✅ Selected Task ID: {task_id}"
+            except Exception as e:
+                return None, f"❌ Error selecting task: {str(e)}"
+
+        task_table.select(
+            fn=on_select_task,
+            inputs=[task_table],
+            outputs=[selected_task_id, selection_info],
+            api_name=False
+        )
+
+        # Button Handlers
+        start_task_btn.click(
+            fn=ui_handlers.set_task_active,
+            inputs=[selected_task_id],
+            outputs=[onboard_status, task_table, progress_bar],
+            api_name=False
+        )
+
+        mark_done_btn.click(
+            fn=ui_handlers.mark_task_done,
+            inputs=[selected_task_id],
+            outputs=[onboard_status, task_table, progress_bar],
+            api_name=False
+        )
+
+        delete_task_btn.click(
+            fn=ui_handlers.delete_task,
+            inputs=[selected_task_id],
+            outputs=[onboard_status, task_table, progress_bar],
+            api_name=False
+        )
+
+        # Monitoring
+        if launch_mode == "demo":
+            demo_update_btn.click(
+                fn=ui_handlers.focus_monitor.update_demo_text,
+                inputs=[demo_textarea],
+                outputs=[demo_status],
+                api_name=False
+            )
+            # Auto-activate timer in demo mode
+            app.load(fn=lambda: gr.update(active=True), outputs=monitor_timer, api_name=False)
+
+            # Toggle handler for demo mode
+            def toggle_demo_timer(active):
+                new_state = not active
+                btn_label = "▶️ Start Auto-Check" if active else "⏸️ Pause Auto-Check"
+                return gr.update(active=new_state), gr.update(value=btn_label), new_state
+
+            # We need a state to track timer status for the button label
+            timer_active_state = gr.State(value=True)
+
+            timer_toggle_btn.click(
+                fn=toggle_demo_timer,
+                inputs=[timer_active_state],
+                outputs=[monitor_timer, timer_toggle_btn, timer_active_state],
+                api_name=False
+            )
+
+        else:
+            start_monitor_btn.click(
+                fn=lambda p: ui_handlers.start_monitoring(p, launch_mode),
+                inputs=[watch_path_input],
+                outputs=[monitor_status, monitor_timer],
+                api_name=False
+            )
+            stop_monitor_btn.click(
+                fn=ui_handlers.stop_monitoring,
+                outputs=[monitor_status, monitor_timer],
+                api_name=False
+            )
+
+            # Toggle handler for local mode (if needed, but local mode uses start/stop buttons)
+            # The button is present in local mode too: "Start Auto-Check"
+            # But local mode logic is tied to file monitoring start/stop.
+            # Let's map it to start/stop monitoring if it's the same intention,
+            # or just pause the timer while keeping monitoring active?
+            # Given the button label "Start Auto-Check", it seems redundant with "Start" button in Monitor tab.
+            # But let's make it toggle the timer.
+
+            def toggle_local_timer(active):
+                new_state = not active
+                btn_label = "▶️ Start Auto-Check" if active else "⏸️ Pause Auto-Check"
+                return gr.update(active=new_state), gr.update(value=btn_label), new_state
+
+            timer_active_state = gr.State(value=False)
+
+            timer_toggle_btn.click(
+                fn=toggle_local_timer,
+                inputs=[timer_active_state],
+                outputs=[monitor_timer, timer_toggle_btn, timer_active_state],
+                api_name=False
+            )
+
+
+        # Pomodoro Handlers
+        pomodoro_start_btn.click(fn=pomodoro_timer.start, outputs=pomodoro_display, api_name=False)
+        pomodoro_stop_btn.click(fn=pomodoro_timer.pause, outputs=pomodoro_display, api_name=False)
+        pomodoro_reset_btn.click(fn=pomodoro_timer.reset, outputs=pomodoro_display, api_name=False)
+
+        # Pomodoro Tick (1 second)
+        pomodoro_ticker.tick(fn=pomodoro_timer.tick, outputs=[pomodoro_display, alert_trigger])
+        # Note: tick returns (display, should_play_sound).
+        # But alert_trigger is HTML. I need a wrapper.
+
+        def pomodoro_tick_wrapper():
+            display, play_sound = pomodoro_timer.tick()
+            js = ""
+            if play_sound:
+                js = """
+                <script>
+                (function() {
+                    const audio = document.getElementById('pomodoro-alert');
+                    if (audio) { audio.play(); }
+                })();
+                </script>
+                """
+            return display, js
+
+        pomodoro_ticker.tick(fn=pomodoro_tick_wrapper, outputs=[pomodoro_display, alert_trigger], api_name=False)
+
+        # Focus Check Tick (Monitor Interval)
+        def monitor_tick_wrapper():
+            focus_result, alert_js, voice_data = ui_handlers.focus_monitor.run_check()
+            alert_html = f'<script>{alert_js}</script>' if alert_js else ""
+            voice_update = gr.update(visible=True, value=voice_data) if voice_data else gr.update(visible=False)
+            return focus_result, alert_html, voice_update
+
+        monitor_timer.tick(
+            fn=monitor_tick_wrapper,
+            outputs=[focus_log, alert_trigger, voice_audio],
+            api_name=False
+        )
+
+        manual_check_btn.click(
+            fn=monitor_tick_wrapper,
+            outputs=[focus_log, alert_trigger, voice_audio],
+            api_name=False
+        )
+
+        # Dashboard
+        refresh_dashboard_btn.click(
+            fn=ui_handlers.refresh_dashboard,
+            outputs=[today_focus_score, today_streak, today_checks, state_plot, weekly_plot],
+            api_name=False
+        )
+        app.load(
+            fn=ui_handlers.refresh_dashboard,
+            outputs=[today_focus_score, today_streak, today_checks, state_plot, weekly_plot],
+            api_name=False
+        )
+
+    return app

voice.py

@@ -0,0 +1,189 @@
+"""
+ElevenLabs Voice Integration for FocusFlow.
+Provides optional voice feedback for focus agent and Pomodoro timer.
+Gracefully falls back to text-only mode if API key is missing or quota exceeded.
+"""
+import os
+import tempfile
+from typing import Optional, Dict
+from pathlib import Path
+
+
+class VoiceGenerator:
+    """
+    Handles text-to-speech generation using ElevenLabs API.
+    Designed for graceful degradation - never crashes if voice unavailable.
+    """
+    
+    def __init__(self):
+        """Initialize ElevenLabs client if API key available."""
+        self.client = None
+        self.available = False
+        self.voice_id = "JBFqnCBsd6RMkjVDRZzb"  # George - friendly, clear voice
+        self.model_id = "eleven_turbo_v2_5"  # Fast, low-latency model
+        
+        try:
+            # Check for API key (demo key first, then user key)
+            api_key = os.getenv("DEMO_ELEVEN_API_KEY") or os.getenv("ELEVEN_API_KEY")
+            
+            if not api_key:
+                print("ℹ️ ElevenLabs: No API key found. Voice feedback disabled (text-only mode).")
+                return
+            
+            # Try to initialize client
+            from elevenlabs.client import ElevenLabs
+            self.client = ElevenLabs(api_key=api_key)
+            self.available = True
+            
+            key_type = "demo" if os.getenv("DEMO_ELEVEN_API_KEY") else "user"
+            print(f"✅ ElevenLabs voice initialized ({key_type} key)")
+            
+        except ImportError:
+            print("⚠️ ElevenLabs: Package not installed. Run: pip install elevenlabs")
+        except Exception as e:
+            print(f"⚠️ ElevenLabs: Initialization failed: {e}")
+    
+    def text_to_speech(self, text: str, emotion: str = "neutral") -> Optional[str]:
+        """
+        Convert text to speech and return path to temporary audio file.
+        
+        Args:
+            text: Text to convert to speech
+            emotion: Emotion hint (not used in current implementation)
+        
+        Returns:
+            Path to temporary MP3 file, or None if voice unavailable
+        """
+        # Check if voice is enabled globally
+        if os.getenv("VOICE_ENABLED", "true").lower() == "false":
+            return None
+        
+        if not self.available or not self.client:
+            return None
+        
+        try:
+            # Generate audio using ElevenLabs API
+            audio = self.client.text_to_speech.convert(
+                text=text,
+                voice_id=self.voice_id,
+                model_id=self.model_id,
+                output_format="mp3_44100_128"
+            )
+            
+            # Convert generator/stream to bytes
+            audio_bytes = b"".join(audio)
+            
+            # Save to temporary file (Gradio expects file path, not data URL)
+            temp_file = tempfile.NamedTemporaryFile(
+                delete=False,
+                suffix=".mp3",
+                prefix="focusflow_voice_"
+            )
+            temp_file.write(audio_bytes)
+            temp_file.close()
+            
+            return temp_file.name
+            
+        except Exception as e:
+            # Graceful degradation - log error but don't crash
+            print(f"⚠️ ElevenLabs: TTS failed: {e}")
+            return None
+    
+    def get_focus_message_audio(self, verdict: str, message: str) -> Optional[str]:
+        """
+        Generate voice feedback for focus check results.
+        
+        Args:
+            verdict: "On Track", "Distracted", or "Idle"
+            message: Text message to speak
+        
+        Returns:
+            Path to temporary audio file or None
+        """
+        if not self.available:
+            return None
+        
+        # Add emotion/tone based on verdict (for future voice modulation)
+        emotion_map = {
+            "On Track": "cheerful",
+            "Distracted": "concerned",
+            "Idle": "motivating"
+        }
+        
+        emotion = emotion_map.get(verdict, "neutral")
+        return self.text_to_speech(message, emotion=emotion)
+    
+    def get_pomodoro_audio(self, event_type: str) -> Optional[str]:
+        """
+        Generate voice alerts for Pomodoro timer events.
+        
+        Args:
+            event_type: "work_complete" or "break_complete"
+        
+        Returns:
+            Path to temporary audio file or None
+        """
+        if not self.available:
+            return None
+        
+        messages = {
+            "work_complete": "Great work! Time for a 5-minute break. You've earned it!",
+            "break_complete": "Break's over! Let's get back to work and stay focused!"
+        }
+        
+        message = messages.get(event_type, "Timer complete!")
+        return self.text_to_speech(message, emotion="cheerful")
+    
+    def test_voice(self) -> Dict[str, any]:
+        """
+        Test voice generation (for setup/debugging).
+        
+        Returns:
+            Dict with status, message, and optional audio data
+        """
+        if not self.available:
+            return {
+                "status": "unavailable",
+                "message": "Voice not available (no API key or initialization failed)",
+                "audio": None
+            }
+        
+        try:
+            test_message = "Hello! FocusFlow voice is working perfectly!"
+            audio = self.text_to_speech(test_message)
+            
+            if audio:
+                return {
+                    "status": "success",
+                    "message": "Voice test successful!",
+                    "audio": audio
+                }
+            else:
+                return {
+                    "status": "error",
+                    "message": "Voice generation failed",
+                    "audio": None
+                }
+        except Exception as e:
+            return {
+                "status": "error",
+                "message": f"Voice test failed: {str(e)}",
+                "audio": None
+            }
+
+
+# Global voice generator instance
+voice_generator = VoiceGenerator()
+
+
+def get_voice_status() -> str:
+    """
+    Get human-readable voice status for UI display.
+    
+    Returns:
+        Status string like "✅ ElevenLabs Voice Enabled" or "ℹ️ Voice Disabled"
+    """
+    if voice_generator.available:
+        return "✅ ElevenLabs Voice Enabled"
+    else:
+        return "ℹ️ Voice Disabled (text-only mode)"