Guidon's Eye 👁️

A privacy-first AI productivity coach for Windows that tracks focus time locally.

Features • Installation • Architecture • Privacy • Contributing • License

---

🎯 Overview

Guidon's Eye is an intelligent productivity assistant designed for developers, students, and knowledge workers who need to safeguard their focus without sacrificing their data privacy.

The Problem

Most productivity trackers operate in the cloud, exposing your detailed activity data and potentially selling it. Traditional app blockers are also too rigid, often killing applications and causing data loss—destroying unsaved work and breaking your workflow.

The Solution (USP)

Guidon's Eye offers Local-First AI Coaching with three core advantages:

1. 📊 Intelligent Activity Tracking — Understands what you're doing and when you're most productive
2. 🛡️ Soft Blocking — Minimizes distracting windows instead of killing processes (no data loss)
3. 🔒 100% Local — All data stays on your machine. Zero telemetry. Your focus is your business.

---

✨ Features

📈 Activity Tracking

• Second-level precision logging of active window time
• Smart categorization: Coding, Browsing, Communication, Gaming, Productivity
• Daily/Weekly reports on screen time usage with visual breakdowns
• Real-time dashboard showing top apps and productivity patterns

🛡️ Intelligent App Blocker

• Smart Blocking: When a limit is reached, the app minimizes the distracting window and shows a persistent overlay
• Non-Destructive: Unlike rigid blockers, it doesn't kill the process immediately, allowing you to save work
• Escalation Protocol: If you persistently attempt to bypass the block (>3 times in a short window), the app escalates to "Force Close" to enforce discipline
• Configurable Limits: Set daily usage caps per application

🤖 AI Productivity Coach

• Context Awareness: Analyzes your current activity, recent apps, and screen time to offer relevant advice
• Multi-Provider Support:
  • Google Gemini 2.5 Flash (recommended, faster & cheaper)
  • Perplexity Sonar (for latest information)
• Circuit Breaker Pattern: Automatically handles API failures with exponential backoff and graceful degradation
• Personalized Insights: "You're most productive 9-11am, consider scheduling deep work then"

⚙️ Settings & Customization

• Configure daily limits per app
• Customize Focus Session durations (Pomodoro-style: Work/Short Break/Long Break)
• Manage AI API keys and switch providers on-the-fly
• Privacy Mode toggle (disable detailed logging)

---

🚀 Installation

System Requirements

Requirement	Details
OS	Windows 10/11 (22H2+)
Node.js	v18.x or higher
Electron	v40.0.0
Database	MongoDB (Local Instance)
RAM	4GB minimum, 8GB recommended
Disk	500MB for installation + database

Step-by-Step Setup

1. Clone the Repository

git clone https://github.com/yourusername/guidons-eye.git
cd guidons-eye

2. Install Dependencies

npm install

3. MongoDB Setup

Option A: Direct Installation (Recommended)

• Download from MongoDB Community Edition
• Install with default settings
• MongoDB service will auto-start on boot

Option B: Docker (Advanced)

docker run -d -p 27017:27017 --name mongodb mongo:latest

Verify MongoDB is running:

mongod --version  # Should output version info

4. Environment Configuration

Create a .env file in the project root:

# Google Gemini (Recommended)
GEMINI_API_KEY=AIza_your_key_here

# Perplexity (Optional)
# PERPLEXITY_API_KEY=pplx-your_key_here

# Logging
LOG_LEVEL=info

# MongoDB Connection (Default)
MONGODB_URI=mongodb://127.0.0.1:27017/guidons_eye

# Privacy Settings
PRIVACY_MODE=false

Getting API Keys:

• Gemini: Visit Google AI Studio, create a new API key, copy it
• Perplexity: Sign up at Perplexity.ai, generate API key from settings

5. Run Development Server

npm run dev

The app will launch. On first run:

• Onboarding wizard explains activity tracking
• Requests permission for system-level window detection
• Validates MongoDB connection
• Prompts you to add an AI provider key (optional but recommended)

---

📋 Usage

Dashboard

Access the main dashboard to view:

• Today's Screen Time (pie chart by category)
• Top 5 Apps used with time spent
• Productivity Score (based on app categorization)
• Upcoming Limits and Focus Sessions

Setting App Limits

1. Click "Settings" → "App Limits"
2. Select an app from "Installed Apps" or "Recent Apps"
3. Set a daily limit (in minutes)
4. Choose escalation behavior:
   • Soft Block Only (minimize on limit reached)
   • Escalate to Force Close (after 3 re-opens)

Using the AI Coach

1. Click the AI Chat button (floating icon)
2. Ask questions like:
   • "What was I productive on today?"
   • "Why am I spending so much time on YouTube?"
   • "Give me a focus plan for tomorrow"
3. The AI analyzes your activity and provides personalized coaching
4. Chat history is saved locally

Focus Sessions

1. Click "Start Focus" in the dashboard
2. Choose session type:
   • Work (25 min)
   • Short Break (5 min)
   • Long Break (15 min)
3. Customize durations in Settings if needed
4. During focus, distracting apps trigger soft-block automatically

---

🏗️ Architecture

Technology Stack

Layer	Technology
Runtime	Electron 40 (Chromium + Node.js)
Frontend	Vanilla HTML/CSS/JavaScript
Backend	Node.js (Main Process)
Database	MongoDB (Local Instance)
AI APIs	Google Gemini, Perplexity Sonar
HTTP Client	Axios with Circuit Breaker
Logging	Winston (JSON format)

Project Structure

guidons-eye/
├── src/
│   ├── main/
│   │   ├── index.js              # Electron main process
│   │   ├── preload.js            # Secure IPC bridge
│   │   └── ipc-handlers/         # Main process event handlers
│   ├── renderer/
│   │   ├── index.html            # Main UI shell
│   │   ├── css/                  # Stylesheets (dark mode)
│   │   └── js/
│   │       ├── dashboard.js      # Dashboard logic
│   │       ├── settings.js       # Settings panel
│   │       └── chat.js           # AI coach interface
│   ├── services/
│   │   ├── ActivityTracker.js    # Window polling & logging
│   │   ├── AppBlocker.js         # Limit enforcement
│   │   ├── AIService.js          # Gemini/Perplexity integration
│   │   └── CircuitBreaker.js     # API failure handling
│   ├── os-integration/
│   │   ├── WindowDetector.js     # Win32 API (active window)
│   │   └── ProcessController.js  # Process termination (safe)
│   ├── database/
│   │   ├── connection.js         # MongoDB setup
│   │   └── models/               # Activity, Limit, Goal schemas
│   └── utils/
│       ├── Logger.js             # Winston logger config
│       └── Config.js             # Environment & config loading
├── .env.example                   # Environment template
├── electron-builder.json          # Build configuration
└── package.json                   # Dependencies & scripts

Data Flow

User Activity
    ↓
WindowDetector (polls active window every 2 sec)
    ↓
ActivityTracker (logs app + category + duration)
    ↓
MongoDB (stores to activity_log collection)
    ↓
Dashboard UI (renders real-time charts)
    ↓
AI Coach (analyzes weekly patterns, generates insights)

IPC Security

The renderer process is sandboxed with context isolation enabled. It communicates with the main process only through a secure preload bridge:

// renderer can call these safe methods only:
window.api.getActiveWindow()
window.api.setAppLimit(appName, minutes)
window.api.sendChatMessage(prompt)
// No direct Node.js filesystem, process, or shell access

API Integration (Circuit Breaker Pattern)

Gemini/Perplexity calls use exponential backoff:

Request 1: Fails → Wait 1s
Request 2: Fails → Wait 2s
Request 3: Fails → Wait 4s
Max 3 retries → Show user: "AI temporarily unavailable"

---

🔒 Privacy & Security

Zero Telemetry

We do not collect any usage data, analytics, or crash reports. Logs stay on your machine exclusively.

Window Title Protection

By default, specific window titles (e.g., "Q3_Report.docx", "Budget.xlsx") are stripped before logging. Only the application name (e.g., "Microsoft Word", "Excel") is stored.

Example:

Raw: "Budget.xlsx - Microsoft Excel"
Logged: "Microsoft Excel" (app name only)

Process Isolation

• Renderer Process: Runs with sandbox: true and contextIsolation: true
• No Node Integration: Renderer cannot directly access filesystem, shell, or OS APIs
• CSP Header: Strict Content Security Policy prevents inline scripts

API Key Management

• API keys are stored only in .env (local file, not in repo)
• Keys are never logged or exposed in debug output
• .gitignore ensures .env is never committed
• Requests to AI providers are encrypted (HTTPS)

Data Deletion

You have full control. To delete all data:

1. Export: Settings → "Export All Data" (JSON file)
2. Delete: Settings → "Delete All Data" → Confirm
3. Database files and logs are wiped from ~/.guidons-eye/

---

🔧 Configuration

.env Variables

# AI Providers (Choose at least one)
GEMINI_API_KEY=AIza_...              # Google Gemini v2.5 Flash
PERPLEXITY_API_KEY=pplx-...          # Perplexity Sonar

# Database
MONGODB_URI=mongodb://127.0.0.1:27017/guidons_eye

# Logging
LOG_LEVEL=info                       # debug | info | warn | error
LOG_DIR=~/.guidons-eye/logs

# Privacy
PRIVACY_MODE=false                   # true = disable detailed logging
WINDOW_TITLE_LOGGING=false           # Never log raw window titles

# App Blocker
ENABLE_FORCE_QUIT=false              # Disable force-close by default
SOFT_BLOCK_TIMEOUT=30000             # Milliseconds before escalation

# Focus Sessions
DEFAULT_WORK_DURATION=25             # Minutes
DEFAULT_SHORT_BREAK=5                # Minutes
DEFAULT_LONG_BREAK=15                # Minutes

---

🐛 Troubleshooting

MongoDB Connection Error

Error: MongooseError: connect ECONNREFUSED 127.0.0.1:27017

Solution:

# Windows: Start MongoDB service
net start MongoDB

# Or manually run:
mongod

# macOS/Linux: Check if running
ps aux | grep mongod

Gemini API Errors

Error	Cause	Fix
401 Unauthorized	Invalid API key	Verify key starts with AIza_...
429 Too Many Requests	Rate limited	Wait 60 seconds, Circuit Breaker will retry
503 Service Unavailable	API down	Check Google Cloud Status, app will retry

App Limits Not Triggering

Check:

1. Limit name matches executable name (e.g., chrome.exe, not Chrome)
2. App is in the Installed Apps list
3. Limit time has actually been exceeded (check dashboard timer)

Debug:

# View activity logs
tail -f ~/.guidons-eye/logs/activity.log

# Check app name matching
npm run debug:apps

High CPU/Memory Usage

Normal behavior: ~50-100MB RAM at idle, <5% CPU during polling.

If spiking:

1. Check MongoDB isn't stuck: mongosh → db.serverStatus()
2. Disable privacy mode (may be processing heavy logs)
3. Reduce polling frequency in Settings

Uninstall & Data

• App files: Removed by Windows Add/Remove Programs
• User data: Stays in %APPDATA%/Guidon's Eye/ (requires manual deletion)
• Logs: Located in ~/.guidons-eye/logs/ (safe to delete)

---

Development Setup

# Clone & install
git clone https://github.com/yourusername/guidons-eye.git
cd guidons-eye
npm install

# Create .env from template
cp .env.example .env

# Start dev mode (hot reload)
npm run dev

# Run linter
npm run lint

# Build for production
npm run build

---

📄 License

MIT License — See LICENSE file for full text.

---

📊 Project Status

• Current Version: 0.1.0 (Alpha)
• Last Updated: January 22, 2026
• Maintenance Status: Active Development
• Contributors: Welcome!

⬆ Back to Top