FocusPilot OS 🛡️

An Autonomous AI Control Plane for Cognitive Resilience and Human-Centric Productivity.

FocusPilot OS is not a task manager. It is a supportive autonomy system designed to protect your focus by dynamically adjusting your work plan based on real-time cognitive load, energy levels, and fragmentation risk. It acts as a "Cognitive Shield" that moves tasks, inserts breaks, and buffers distractions so you can stay in flow.

---

🏗️ Architecture Overview

FocusPilot operates on a Heuristic-Agentic closed loop:

1. Behavioral Telemetry: Monitors "signals" like window switching frequency, meeting density, and activity bursts.
2. Risk Agent (Heuristic): Transforms telemetry into structured metrics: Overload (cognitive volume) and Fragmentation (context switching).
3. Planning Agent (LLM): Uses Google Gemini to reason about the risk state and propose schedule adaptations (e.g., Load Shedding or Focus Protection).
4. Observability HUD: A React-based interface that visualizes the system's "internal state" and explains the "Why" behind every change.

Tech Stack

• Backend: Python 3.10+, FastAPI, Pydantic.
• AI Core: Google Gemini (via google-genai).
• Observability: Comet Opik (Native LLM Tracing & Evaluation).
• Frontend: React, Vite, Framer Motion (Animations), Recharts (Energy Visualization).

---

🚀 Getting Started

Prerequisites

• Node.js (v18 or higher)
• Python (v3.10 or higher)
• Google Gemini API Key (Get it here)
• Comet Opik API Key (Get it here)

1. Backend Setup

cd backend
pip install -r requirements.txt
cp .env.example .env

Configure .env:

GOOGLE_API_KEY=your_gemini_key
OPIK_API_KEY=your_comet_key
OPIK_WORKSPACE=your_workspace_name
OPIK_PROJECT_NAME=focus-pilot-os

2. Launching the OS

Start the Control Plane (Backend):

# In the /backend directory
export PYTHONPATH=$PYTHONPATH:.
python3 main.py

The API will be available at http://localhost:8000.

Start the Observability HUD (Frontend):

# In the /frontend directory
npm install
npm run dev

The UI will be available at http://localhost:5173.

---

🧪 How to Test & Verify

Phase 1: The Health Check

Visit http://localhost:8000/health in your browser. You should receive: {"status": "active", "version": "0.1.0-mvp"}

Phase 2: Live Recalibration

1. Open the Frontend HUD.
2. Observe the Focus Stack. Look for tasks marked with the ✨ "Adjusted" badge.
3. Click the "Sync Focus" button in the header.
4. Watch the transition—the PlanningAgent will run a fresh cycle, and you'll see the "System Observations" update with real-time reasoning from Gemini.

Phase 3: Audit the Brain (Opik)

1. Log in to your Comet/Opik dashboard.
2. Open the focus-pilot-os project.
3. Every time you clicked "Sync Focus," a new trace was generated. You can see the exact context (Overload/Fragmentation scores) and how the LLM brainstormed the new schedule.

---

🌐 Deployment

FocusPilot OS is structured for easy deployment with standard cloud tools.

1. Backend (Heroku / Render / Railway)

The backend is container-ready and includes a Procfile.

• Platform: Render or Heroku
• Root Directory: backend/
• Build Command: pip install -r requirements.txt
• Start Command: python main.py
• Environment Variables:
  • GOOGLE_API_KEY: Your Gemini API key.
  • OPIK_API_KEY: Your Opik API key.
  • OPIK_PROJECT_NAME: focus-pilot-os
  • PORT: Automatically set by most platforms.

Docker: You can also deploy as a container using the provided backend/Dockerfile.

2. Frontend (Netlify / Vercel)

The frontend is a Vite SPA.

• Platform: Netlify
• Base Directory: frontend/
• Build Command: npm run build
• Publish Directory: dist/
• Environment Variables:
  • VITE_API_URL: The URL of your deployed backend (e.g., https://your-backend.onrender.com).

---

🧠 Explaining FocusPilot to a New User

When introducing FocusPilot, use these three anchors to build trust:

1. "It's about Rhythm, not Deadlines": Point at the Energy Wave. Explain that the system isn't checking a clock; it's monitoring your "Cognitive Pressure." When the pressure spikes, the system makes space for you to breathe.
2. "Supportive Autonomy": Explain the ✨ "Adjusted" badge. Tell the user: "The system moved your Deep Work task because it detected you were being fragmented by meetings. It's protecting your best energy for your best work."
3. "Why, not just What": Show the System Observations. Emphasize that every decision is backed by a "How" and a "Why," and the user can always override the system if they choose.

FocusPilot OS isn't here to control you—it's here to ensure that by the time you sit down to work, the plan is already aligned with your mental state.

---