MindfulIDE 🧘‍♀️

A mindful IDE extension that promotes wellbeing during AI coding downtime with guided breathing exercises.

Overview

MindfulIDE solves the problem of wasted downtime and mental fatigue during AI-assisted coding. Instead of context-switching to your phone during 1-5 minute inference gaps, MindfulIDE offers guided breathing exercises that help you stay focused, reduce stress, and return to coding with renewed energy.

Features

Two Science-Based Breathing Exercises

😌 Cyclic Sighing (Increase Relaxation)

• Pattern: Two inhales → Long exhale
• Duration: ~6 minutes (6 cycles)
• Purpose: Reduce stress and calm the nervous system
• Research: Based on physiological sigh technique proven to activate parasympathetic response

⚡ Cyclic Hyperventilation (Increase Alertness)

• Pattern: Rapid deep inhales → Slower exhales
• Duration: ~2 minutes (30 cycles)
• Purpose: Boost energy and mental alertness
• Similar to: Wim Hof breathing method

Key Capabilities

• Beautiful Animations: Smooth, calming breathing visualizations with Framer Motion
• Session Tracking: Automatic tracking of all mindfulness sessions
• Statistics Dashboard: Track your mindfulness journey with detailed stats
  • Total sessions completed
  • Total time spent being mindful
  • Current and longest streaks
  • Sessions by exercise type
• Downtime Detection: Smart idle detection suggests breathing exercises after 2 minutes
• Progress Tracking: Real-time cycle and time tracking during exercises

Tech Stack

Frontend

• React 18 with TypeScript
• Vite for fast development
• Tailwind CSS for styling
• Framer Motion for smooth animations
• Zustand for state management
• Axios for API calls

Backend

• Node.js with Express
• TypeScript for type safety
• SQLite with better-sqlite3 for session storage
• RESTful API design

Project Structure

MindfulIDE/
├── frontend/                     # React frontend
│   ├── src/
│   │   ├── components/
│   │   │   ├── BreathingCircle.tsx      # Animated breathing visualization
│   │   │   ├── BreathingExercise.tsx    # Main exercise component
│   │   │   ├── ExerciseSelector.tsx     # Exercise selection UI
│   │   │   └── StatsDashboard.tsx       # Statistics display
│   │   ├── hooks/
│   │   │   └── useBreathingCycle.ts     # Breathing cycle logic
│   │   ├── utils/
│   │   │   └── api.ts                   # API client
│   │   └── App.tsx                      # Main app component
│   └── package.json
│
├── backend/                      # Express backend
│   ├── src/
│   │   ├── database/
│   │   │   └── db.ts                    # SQLite setup
│   │   ├── models/
│   │   │   └── Session.ts               # Session data model
│   │   ├── routes/
│   │   │   ├── sessions.ts              # Session endpoints
│   │   │   └── stats.ts                 # Statistics endpoints
│   │   └── index.ts                     # Express server
│   └── package.json
│
├── shared/                       # Shared types & constants
│   ├── types/
│   │   └── breathing.ts                 # TypeScript interfaces
│   └── constants/
│       └── breathingPatterns.ts         # Exercise definitions
│
└── package.json                  # Monorepo root

Getting Started

Prerequisites

• Node.js 18+ and npm
• Git

Installation

1. Clone the repository

   git clone <your-repo-url>
   cd MindfulIDE

2. Install dependencies

   npm install
   cd frontend && npm install
   cd ../backend && npm install
   cd ..

3. Set up environment variables

   cp frontend/.env.example frontend/.env
   cp backend/.env.example backend/.env

4. Run the application

   # From root directory - runs both frontend and backend
   npm run dev

   Or run separately:

   # Terminal 1 - Backend (port 5000)
   cd backend && npm run dev
   
   # Terminal 2 - Frontend (port 3000)
   cd frontend && npm run dev

5. Open your browser

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:5000/api

API Endpoints

Sessions

• POST /api/sessions - Create a new session
• PATCH /api/sessions/:id - Update a session
• GET /api/sessions/:id - Get session by ID
• GET /api/sessions - Get all sessions (limit query param)

Statistics

• GET /api/stats - Get aggregated statistics

Health

• GET /api/health - Health check endpoint

Usage

Starting a Breathing Exercise

1. Select an exercise from the home screen

   • Choose "Cyclic Sighing" for relaxation
   • Choose "Cyclic Hyperventilation" for alertness

2. Click Start when ready

3. Follow the visual cues

   • Circle expands during inhale
   • Circle contracts during exhale
   • Read on-screen instructions

4. Complete the session

   • Progress bar shows current cycle
   • Timer shows elapsed time
   • Can pause/resume anytime

Viewing Statistics

Click "View Stats" to see:

• Total mindfulness sessions completed
• Total time spent in mindfulness
• Current daily streak
• Longest streak achieved
• Breakdown by exercise type
• Average session duration

Breathing Patterns Explained

Cyclic Sighing (Relaxation)

Pattern: Inhale (2s) → Inhale (2s) → Exhale (6s)

How it works:

1. First inhale through nose (fill lungs 80%)
2. Quick second inhale through nose (top off to 100%)
3. Long, slow exhale through mouth (empty completely)

Benefits:

• Activates parasympathetic nervous system
• Reduces heart rate and blood pressure
• Decreases stress hormones (cortisol)
• Improves emotional regulation

Best for:

• After a stressful debugging session
• Before important code reviews
• When feeling overwhelmed

Cyclic Hyperventilation (Alertness)

Pattern: Deep Inhale (1.5s) → Passive Exhale (2.5s)

How it works:

1. Deep, rapid inhale through nose or mouth
2. Let the exhale happen passively (don't force it)
3. Repeat rapidly for 30 cycles

Benefits:

• Increases oxygen in blood
• Boosts adrenaline and energy
• Enhances mental clarity
• Improves focus and alertness

Best for:

• Early morning coding sessions
• After lunch energy dip
• Before tackling complex problems

Development

Running Tests

# Frontend tests
cd frontend && npm test

# Backend tests
cd backend && npm test

Building for Production

# Build both frontend and backend
npm run build

# Or separately
npm run build:frontend
npm run build:backend

Database

The SQLite database is stored at backend/data/mindful.db and includes:

• Session history
• Exercise completion data
• Timestamps for streak calculation

Future Enhancements

• VS Code extension integration
• Real-time AI downtime detection hooks
• Audio cues and ambient sounds
• Custom breathing pattern creator
• Multi-user support with authentication
• Mobile app version
• Integration with other IDEs (JetBrains, Sublime)
• Biometric data integration (Apple Watch, Fitbit)
• Team/workplace mindfulness challenges
• Export data to CSV/JSON

Inspiration

This project was inspired by:

• Whoop: For their excellent breathing exercise implementations
• ChadIDE: For highlighting the downtime problem during AI coding
• Research: Neuroscience studies on breathing and stress reduction

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - feel free to use this project however you'd like!

Acknowledgments

• Research on physiological sighs by Stanford's Huberman Lab
• Wim Hof Method for cyclic hyperventilation technique
• All developers struggling with AI coding downtime

---

Built with 🧘 by developers, for developers

Stay mindful, code better! 🚀