📖 Table of Contents

• What is Focus Pulse?
• Why Choose Focus Pulse?
• Features
• What's New in 2.5.0
• Installation
• Quick Start
• Dashboard Preview
• How It Works
• Meet Your AI Assistant
• Cloud Sync & Data Management
• Gamification System
• Commands
• Settings
• Use Cases
• FAQ
• Roadmap
• Contributing
• License

🎯 What is Focus Pulse?

Focus Pulse is a gamified productivity system that lives inside VS Code and helps you:

✨ Stay focused — Real-time tracking of your attention span 🤖 Get AI guidance — Predictive assistant that prevents burnout 🎮 Level up — XP, achievements, and progression system 📊 Understand yourself — Peak performance analysis and insights 🔥 Build streaks — Daily consistency tracking ☁️ Sync everywhere — Cloud-enabled progress across devices

Not a time tracker. Not a task manager. Not a Pomodoro app. It's your personal focus coach that measures quality, not just quantity.

🚀 Why Choose Focus Pulse?

🆚 Comparison with Other Tools

✨ Features

🤖 AI-Powered Virtual Assistant (v2.4+)

Your intelligent coding companion that learns your patterns and guides your focus journey.

• 🔮 Predictive Fatigue Detection — Warns you 10-15 minutes BEFORE burnout hits (uses linear regression on score trends)
• ⏰ Peak Performance Analysis — Identifies your best working hours and most productive days
• 📊 Git Activity Insights — Celebrates commits, merges, PRs, and coding streaks in real-time
• 🌊 Flow State Protection — Detects "the zone" and avoids interruptions
• 🎭 4 Personalities — Motivador, Zen, Humorístico, Neutro
• 📁 Context-Aware Messages — Different advice for tests, docs, frontend, backend code

📈 Real-Time Focus Tracking

• Focus Score (0-100) — Calculated from time, edits/min, and context switching
• Live Dashboard — Updates every 2 seconds while you code
• Per-File Analytics — See which files get your best focus
• Session Tracking — Automatic start/stop based on your activity

🎮 Gamification Layer

• XP & Levels — RPG-style progression (100 + (level-1) × 50 XP curve)
• 30+ Achievements — Unlock badges for streaks, milestones, deep work
• Custom Achievements — Create your own goals with custom icons/colors
• Daily Goals — Set targets for minutes + pomodoros
• Heatmap — 30-day visual intensity map

⏲️ Pomodoro & Deep Work

• Integrated Pomodoro Timer — 25/5 min cycles with XP bonuses
• Deep Work Mode — 60-90 min sessions with 2.67× context switch penalty
• Smart Breaks — AI suggests optimal rest times
• Streak Tracking — Daily consistency metrics

☁️ Cloud Sync & Data Portability

• Auto-Sync — Configurable intervals (30 min default)
• Version History — Restore any previous sync point
• Multi-Device — Seamless progress across machines
• Export/Import — JSON/XML backup support
• Privacy-First — Only metrics synced, not file names

📊 Advanced Analytics

• Weekly Summary — Total minutes + avg score per week
• Insights Dashboard — Today vs yesterday comparisons
• Trend Analysis — Score variance and consistency metrics
• Best Days Detection — Monday/Wednesday/Friday analysis

🆕 What's New in 2.6.0

👥 Friends System

Compare your Focus Pulse stats with friends directly inside the dashboard. No backend — profiles live as public GitHub Gists.

📋 See full changelog: CHANGELOG.md

🔔 Notification System (2.5.0)

Real-time notifications for every key event in your session. Fires automatically — no setup needed beyond enabling.

Notifications support two styles: native VS Code dialogs and toast overlays in the dashboard. Both can run simultaneously.

{
  "focusPulse.notifications.enabled": true,
  "focusPulse.notifications.style": "toast", // "native" | "toast" | "both"
  "focusPulse.notifications.duration": 5000, // toast duration in ms
}

🐛 Fixes in 2.5.1

• PeakPerformanceAnalyzer crash — day.sessions.forEach is not a function. The hourly analysis expected session objects that were never stored. Rewrote to use the actual history model.
• NotificationService crash on startup — eventBus was referenced before initialization in activate().
• Silent notifications — All notification listeners were registered but the events were never emitted. Wired up POMODORO_COMPLETED, GOAL_COMPLETED, DEEP_WORK_STARTED, DEEP_WORK_ENDED, XP_EARNED across pomodoro.ts, deepWork.ts, and the main update loop.

📋 See full changelog: CHANGELOG.md

📦 Installation

Option 1: VS Code Marketplace (Recommended)

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X or Cmd+Shift+X)
3. Search for "Focus Pulse"
4. Click Install

Option 2: Quick Install

code --install-extension dominguezz05.focus-pulse

Option 3: Manual Install

1. Download the latest .vsix from Releases
2. Open VS Code
3. Ctrl+Shift+P → "Extensions: Install from VSIX"
4. Select the downloaded file

🚀 Quick Start

1️⃣ Open the Dashboard

Method 1: Command Palette Ctrl+Shift+P → Type "Focus Pulse: Abrir dashboard"

Method 2: Status Bar Click on the ⚡ Lvl X · Focus Y item in the bottom status bar

2️⃣ Configure Your Preferences

{
  // Assistant Personality
  "focusPulse.assistant.personality": "motivador", // or "zen", "humorístico", "neutro"

  // Flow Protection (avoid interruptions during high focus)
  "focusPulse.assistant.flowProtection": true,

  // Context-Aware Messages
  "focusPulse.assistant.contextualMessages": true,

  // Daily Goals
  "focusPulse.goals.minutes": 120,
  "focusPulse.goals.pomodoros": 4,

  // Pomodoro Timing
  "focusPulse.pomodoro.workMinutes": 25,
  "focusPulse.pomodoro.breakMinutes": 5
}

3️⃣ Start Coding!

Focus Pulse automatically tracks:

• ✍️ Every keystroke you make
• ⏱️ Time spent on each file
• 🔄 Context switches between files
• 📊 Your focus score in real-time

4️⃣ Watch Your Progress

The AI assistant will:

• 🎉 Celebrate when you level up
• ⚠️ Warn before fatigue hits
• 💡 Suggest optimal work times
• 🏆 Unlock achievements

🖼️ Dashboard Preview

Main Dashboard v2.4

🧮 How It Works

Focus Score Algorithm

Focus Pulse calculates a Focus Score (0-100) based on three signals:

score = (timeMs × 0.3) + (edits/min × 8) - (switches/min × 15)

Score Interpretation

XP System

// Base XP Formula
xp = minutes × (avgScore / 100) × 10

// Bonuses
+ 50 XP per Pomodoro (today)
+ 10 XP per Pomodoro (historical)
+ 150 XP per Deep Work session

// Level Curve
xpToNextLevel = 100 + (currentLevel - 1) × 50

Example Progression:

• Level 1 → 2: 100 XP
• Level 2 → 3: 150 XP
• Level 3 → 4: 200 XP
• Level 10 → 11: 550 XP

🤖 Meet Your AI Assistant

Deepy — Your Focus Companion

Deepy is an AI-powered virtual assistant that lives in your dashboard and adapts to your coding rhythm.

🎨 Visual States

🧠 Intelligence Features

1. Predictive Fatigue Detection

Score History Analysis:
[85, 82, 78, 75, 70] → Decline Rate: 0.6

Prediction:
"📉 Your focus is dropping. Break in 10 min recommended"

2. Peak Performance Tracking

Historical Analysis (30 days):
Best Hour: 10:00 AM (avg score: 88)
Best Day: Tuesday (avg score: 82)

Recommendation:
"⏰ Schedule deep work for Tuesday mornings"

3. Git Activity Celebration

Detected Events:
✨ Feature commit → "Nueva feature! El producto está evolucionando"
🐛 Bug fix → "Bug aplastado! Eres un cazador de bugs"
🔥 5 commits/hour → "RACHA DE COMMITS! Imparable!"
🎉 PR merged → "PR MERGEADO! Tu código está en producción. ÉPICO!"

🌊 Flow State Protection

When you're in "the zone" (score ≥ 75, low switching, 15+ min session), Deepy:

• ✅ Only shows high-priority messages
• ✅ Extends message cooldown by 3×
• ✅ Avoids motivation/tip messages
• ✅ Lets you maintain deep focus

💬 Interactive Features

Click on Deepy to get:

• 🎲 Random productivity fact
• 📊 Your last 7 days git stats
• 💡 Personalized tip based on your history

☁️ Cloud Sync & Data Management

🔐 Authentication

Focus Pulse: Authenticate
  ↓
VS Code OAuth (GitHub)
  ↓
Secure token storage
  ↓
Auto-sync enabled

📤 Sync Workflow

Every 30 minutes (configurable):
  ↓
Collect: history, XP, achievements
  ↓
Serialize to JSON
  ↓
Upload to GitHub via Octokit
  ↓
Version history saved (last 10 syncs)

📥 Multi-Device Sync

Device A (Laptop):
  Code for 2 hours → XP: 500, Level: 5
    ↓ (sync)
  Cloud Storage
    ↓ (sync)
Device B (Desktop):
  Open VS Code → Auto-download → XP: 500, Level: 5 ✅

🛡️ Privacy-First Design

What gets synced:

• ✅ Total XP, level, achievements
• ✅ Daily time totals (minutes)
• ✅ Pomodoro counts
• ✅ Average scores

What stays local:

• ❌ File names/paths
• ❌ Code content
• ❌ Project names
• ❌ Specific timestamps

📂 Manual Backup

Export your entire profile:

# JSON Export
Focus Pulse: Export as JSON
→ focus-pulse-backup-2026-02-04.json

# XML Export
Focus Pulse: Export as XML
→ focus-pulse-backup-2026-02-04.xml

Import anytime:

Focus Pulse: Import data from file
→ Select file
→ Choose: Merge or Overwrite
→ Done!

🎮 Gamification System

🏆 Achievement Categories

Milestone Achievements

Streak Achievements

Pomodoro Achievements

Deep Work Achievements

🎨 Custom Achievements

Create your own goals with the Achievement Builder:

{
  title: "Early Bird 🐦",
  description: "Code before 8 AM for 7 days",
  icon: "🌅",
  color: "blue",
  conditions: {
    streak: 7,
    // Custom logic possible
  }
}

📋 Commands

Dashboard & Stats

Timer Controls

Data Management

Cloud Sync

Achievements

Git Analytics (New! 🆕)

Maintenance

⚙️ Settings

🎯 Core Settings

{
  // Minimum minutes to stabilize score
  "focusPulse.minMinutesForScore": 1,

  // Focus Score weights
  "focusPulse.score.timeWeight": 0.3, // Weight of time on file
  "focusPulse.score.editsWeight": 8, // Weight of edits/min
  "focusPulse.score.switchPenalty": 15, // Penalty for file switching

  // Status bar
  "focusPulse.enableStatusBar": true,
}

⏲️ Pomodoro Settings

{
  "focusPulse.enablePomodoro": true,
  "focusPulse.pomodoro.workMinutes": 25, // Default: 25 min
  "focusPulse.pomodoro.breakMinutes": 5, // Default: 5 min
}

🧠 Deep Work Settings

{
  "focusPulse.deepWork.enabled": true,
  "focusPulse.deepWork.durationMinutes": 60, // Default: 60 min
  "focusPulse.deepWork.switchPenalty": 40, // Extra penalty during DW
  "focusPulse.deepWork.xpBonus": 150, // Bonus XP on completion
}

🎯 Goals Settings

{
  "focusPulse.goals.enabled": true,
  "focusPulse.goals.minutes": 120, // Daily target: 120 min
  "focusPulse.goals.pomodoros": 4, // Daily target: 4 pomodoros
}

🤖 Assistant Settings (New! 🆕)

{
  // Personality: "motivador", "neutro", "zen", "humorístico"
  "focusPulse.assistant.personality": "motivador",

  // Protect Flow State (avoid interruptions during high focus)
  "focusPulse.assistant.flowProtection": true,

  // File-type aware messages (test, frontend, backend, docs, config)
  "focusPulse.assistant.contextualMessages": true,
}

☁️ Sync Settings

{
  "focusPulse.sync.enabled": true,
  "focusPulse.sync.intervalMinutes": 30, // Auto-sync every 30 min
}

🎯 Use Cases

👨‍💻 Solo Developers

"I use Focus Pulse to track my deep work sessions and maintain my coding streak. The AI assistant helps me take breaks before I burn out."

Benefits:

• Self-accountability without team pressure
• Personal analytics and insights
• Gamification keeps solo work engaging

🎓 Students & Bootcamp

"The Pomodoro integration and daily goals help me stay consistent with my coding practice. Achievements make learning fun!"

Benefits:

• Structured learning sessions
• Progress visualization
• Motivation through gamification

🚀 Indie Hackers & Makers

"Focus Pulse helps me maximize my limited coding time. The peak performance analysis shows when I'm most productive."

Benefits:

• Optimize limited time slots
• Data-driven schedule planning
• Track side project momentum

🧠 ADHD-Friendly Workflows

"The real-time feedback and frequent achievements keep me engaged. Flow state protection is a game-changer."

Benefits:

• Immediate feedback loops
• Gamified motivation system
• Break reminders at optimal times
• Visual progress indicators

📊 Productivity Enthusiasts

"I love tracking my metrics. The heatmap and weekly summaries give me clear insights into my coding habits."

Benefits:

• Comprehensive analytics
• Historical trend analysis
• Data export for personal analysis

🏋️ Focus Training

"I'm building my concentration muscle. Focus Pulse shows my score improve week over week."

Benefits:

• Quantified focus improvement
• Context switching awareness
• Progressive difficulty (achievements)

❓ FAQ

General Questions

Features

{
  "focusPulse.score.timeWeight": 0.3, // Default: 0.3
  "focusPulse.score.editsWeight": 8, // Default: 8
  "focusPulse.score.switchPenalty": 15 // Default: 15
}

Data & Privacy

Troubleshooting

# Test if git is accessible
git --version

# Check if current folder is a git repo
git status

🗺️ Roadmap

✅ Completed

• [x] v1.0 — Core focus tracking + dashboard
• [x] v2.0 — Deep Work mode + weekly summaries
• [x] v2.1 — Component-based architecture refactor
• [x] v2.2 — Custom achievements system
• [x] v2.3 — Cloud sync + data export/import
• [x] v2.4.0 — AI Virtual Assistant
• [x] v2.4.1 — Personality system + Flow protection
• [x] v2.4.2 — Predictive AI + Git integration + Peak analysis
• [x] v2.5.0 — Notification system + event architecture
• [x] v2.5.1 — Critical fixes (PeakPerformanceAnalyzer crash, event emissions)
• [x] v2.6.0 — Friends system (gist-based profiles, comparison table, offline cache)

🚧 In Progress (v2.7.0)

• [ ] English-language Support — English languaje
• [ ] Leaderboards — Weekly/monthly rankings (opt-in)

🔮 Future (v3.0+)

• [ ] Mobile Companion App — View stats on phone/tablet
• [ ] Team Analytics — Team-wide focus metrics (privacy-preserving)
• [ ] Integration Hub — Notion, Todoist, Linear connectors
• [ ] AI Coaching — Personalized productivity recommendations
• [ ] Focus Music — Integrated background music based on state
• [ ] Pomodoro Templates — Custom work/break patterns
• [ ] Voice Commands — Start/stop timers with voice

💡 Community Ideas

Have a feature request? Open an issue or vote on existing ones!

🤝 Contributing

We welcome contributions! Here's how you can help:

🐛 Report Bugs

Found a bug? Open an issue with:

• Steps to reproduce
• Expected vs actual behavior
• VS Code version
• Focus Pulse version
• Screenshots (if applicable)

💡 Suggest Features

Have an idea? Start a discussion or create a feature request issue.

🔧 Code Contributions

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

📝 Documentation

Help improve the docs:

• Fix typos or unclear sections
• Add examples and use cases
• Translate to other languages
• Create video tutorials

🎨 Design

Contribute:

• UI/UX improvements
• Icon designs
• Assistant sprites/animations
• Dashboard themes

Development Setup

# Clone the repo
git clone https://github.com/dominguezz05/focus-pulse.git
cd focus-pulse

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Watch mode (auto-compile on save)
npm run watch

# Package extension
npm run package

# Test in VS Code
# Press F5 to open Extension Development Host

📄 License

MIT License

Copyright (c) 2026 Iker Domínguez

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

🙏 Acknowledgments

• VS Code Team — For the amazing extension API
• Contributors — Everyone who has helped improve Focus Pulse
• Community — Beta testers and feedback providers
• You — For using Focus Pulse to level up your coding game!

📞 Support & Community

• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• ⭐ Star the Repo: GitHub
• 📦 Marketplace: VS Code Marketplace
• 📦 Open vsx Registry: VSX Registry ext.