🚀 Interactive Focus Companion
A delightful Pomodoro-style focus timer with animated status bar companions, task management, and celebration effects — built natively for VS Code.
✨ Features
🎯 Focus Timer
- Pomodoro-style sessions with configurable duration (default 25 minutes)
- Start / Pause / Resume / Stop controls from status bar, command palette, or dashboard
- Break timer with optional auto-start after focus sessions
- Extend sessions by 5 minutes when you're in the zone
- Crash recovery — interrupted sessions are saved and can be resumed
🐱 Animated Status Bar
- Live countdown displayed in the status bar during focus sessions
- Animated animal companion that cycles through emoji frames while you focus
- Choose between Cat 🐱, Dog 🐶, or Bird 🐦 animations
- Status bar changes dynamically based on session state (focusing, paused, break)
📊 Dashboard
- Activity Bar sidebar with a rich webview dashboard
- Today View — see completed sessions, total focused minutes, and streak count
- Task Management — create projects, tasks, and subtasks (2-level hierarchy)
- History — browse past daily summaries with visual bar charts
- Link tasks to sessions for focused, intentional work
🎉 Celebration Effects
- Visual celebration on session completion — status bar and activity bar light up in gold
- Editor decorations — subtle golden border appears on your active editor
- Fully configurable colors and duration
- Original theme is always safely restored
🔧 Highly Configurable
All settings available through VS Code's native Settings UI:
- Focus & break durations
- Animal animation style
- Celebration toggle and colors
- Status bar visibility
- Auto-start break behavior
📋 Commands
| Command |
Title |
Description |
focusPomodoro.start |
Focus: Start Session |
Start a new focus session |
focusPomodoro.stop |
Focus: Stop Session |
Stop the current session |
focusPomodoro.pause |
Focus: Pause Session |
Pause the active session |
focusPomodoro.resume |
Focus: Resume Session |
Resume a paused session |
focusPomodoro.openDashboard |
Focus: Open Dashboard |
Open the Focus dashboard |
⚙️ Settings
| Setting |
Default |
Description |
focusCompanion.focusDurationMinutes |
25 |
Duration of focus sessions in minutes |
focusCompanion.breakDurationMinutes |
5 |
Duration of break periods in minutes |
focusCompanion.autoStartBreak |
false |
Auto-start break after focus session |
focusCompanion.showStatusBarItem |
true |
Show status bar item |
focusCompanion.celebration.enabled |
true |
Enable celebration effects |
focusCompanion.celebration.durationMs |
3000 |
Celebration effect duration (ms) |
focusCompanion.celebration.colors |
Gold theme |
Colors applied during celebration |
focusCompanion.animalStyle |
"cat" |
Animal animation (cat/dog/bird) |
focusCompanion.telemetry.enabled |
false |
Anonymous usage telemetry |
🏗️ Architecture
src/
├── extension.ts # Entry point — wires all components
├── commands/
│ └── index.ts # Command registration
├── services/
│ ├── timerService.ts # Focus timer state machine
│ ├── storageService.ts # Memento-based persistence
│ └── celebrationService.ts # Visual celebration effects
├── ui/
│ ├── statusBar.ts # Animated status bar manager
│ └── dashboardProvider.ts # Webview dashboard provider
├── models/
│ └── types.ts # Shared type definitions
└── utils/
└── helpers.ts # Utility functions
Key Design Decisions
- Event-driven architecture —
TimerService emits events consumed by StatusBar and Dashboard independently
- No external dependencies — pure VS Code API + vanilla HTML/CSS/JS webview
- Crash recovery — active sessions are backed up every 30 seconds
- Safe celebration — original theme colors are cached and restored after the celebration window
- esbuild bundling — fast builds, single output file for minimal startup overhead
🚀 Getting Started
Development
# Install dependencies
npm install
# Build the extension
npm run compile
# Watch for changes
npm run watch
Running
- Open this project in VS Code
- Press
F5 to launch the Extension Development Host
- Look for the rocket icon (🚀) in the status bar
- Click it to start your first focus session!
📝 License
MIT
🔮 Future Enhancements
- Cross-device sync via cloud backend
- Integration with Jira, GitHub Issues, Trello
- Rich analytics (weekly/monthly reports, per-project trends)
- AI-assisted daily planning
- Team focus activity view
| |
