Minimalist Focus Timer

🍅 The simplest way to manage your work sprints directly in VS Code

A ultra-minimal Pomodoro timer that lives in your status bar. No distractions, no complex UI, just pure productivity focus. Click to start, work for 25 minutes, take a break. That's it.

✨ Features

🎯 Dead Simple

• One-click operation: Click the status bar to start/stop
• Visual countdown: See exact time remaining
• Smart notifications: Gentle reminders when sessions complete
• Session tracking: Keep count of completed work sessions

⚙️ Highly Customizable

• Work duration: 1-120 minutes (default: 25 min)
• Short breaks: 1-30 minutes (default: 5 min)
• Long breaks: 1-60 minutes (default: 15 min)
• Break intervals: After how many sessions to take long break
• Auto-start: Automatically begin breaks/work sessions
• Notifications: Toggle on/off, customize behavior

🚀 Developer-Focused

• Keyboard shortcuts: Ctrl+Shift+T to start/stop
• Status bar integration: Never leaves your coding flow
• Session persistence: Remembers your progress
• Workspace-specific: Different settings per project

🚀 Installation

From VS Code Marketplace

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "Minimalist Focus Timer"
4. Click Install
5. Look for the 🍅 in your status bar - you're ready!

First Use

1. Click the 🍅 in your status bar to start your first 25-minute focus session
2. Work focused until you get the gentle completion notification
3. Take your break and click again when ready to resume
4. Build productive habits with the Pomodoro technique!

📖 How to Use

Basic Operation

Starting a Session

• Click the 🍅 tomato icon in the status bar
• Or press Ctrl+Shift+T (Windows/Linux) or Cmd+Shift+T (Mac)
• Or use Command Palette: "Focus Timer: Start"

Stopping/Pausing

• Click the timer again to pause
• Or press Ctrl+Shift+T while running
• Or use Command Palette: "Focus Timer: Stop"

Resetting

• Use Command Palette: "Focus Timer: Reset"
• Resets timer and session count

Timer States

🍅 Work Session (Default: 25 min)

• Focus time! No interruptions, just pure productivity
• Status bar shows: 🍅 24:59 (counting down)
• Tooltip shows progress and session count

☕ Short Break (Default: 5 min)

• Quick refresher between work sessions
• Status bar shows: ☕ 04:59
• Perfect for stretching, hydrating, quick walk

🧘 Long Break (Default: 15 min)

• Longer break after multiple work sessions (default: every 4 sessions)
• Status bar shows: 🧘 14:59
• Time for a real break, meal, or movement

⏸️ Paused

• Any session can be paused mid-way
• Click to resume from where you left off

Notifications

When a session completes, you'll see a friendly notification:

• Work Complete: "Work Session Complete! 🎉 Time for a short break (5 minutes)"
• Break Complete: "Break Complete! 💪 Ready for another work session (25 minutes)"

Notification Actions:

• "Start Break"/"Start Working": Immediately begin next session
• "Settings": Open extension settings
• Dismiss: Manual control over when to start next session

⚙️ Configuration

Access settings via File > Preferences > Settings and search for "Focus Timer":

Core Timer Settings

focusTimer.workDuration

Default: 25 minutes
Range: 1-120 minutes
Duration of work sessions (classic Pomodoro is 25 minutes)

focusTimer.shortBreakDuration

Default: 5 minutes
Range: 1-30 minutes
Duration of short breaks between work sessions

focusTimer.longBreakDuration

Default: 15 minutes
Range: 1-60 minutes
Duration of long breaks after multiple work sessions

focusTimer.longBreakInterval

Default: 4 sessions
Range: 2-10 sessions
Number of work sessions before triggering a long break

Behavior Settings

focusTimer.showNotifications

Default: true
Show notifications when timer sessions complete

focusTimer.autoStartBreaks

Default: false
Automatically start break timers (and work sessions after breaks)

focusTimer.showProgress

Default: true
Show progress indicator in status bar tooltip

focusTimer.playSound

Default: false
Play notification sound when sessions complete (system-dependent)

🎮 Commands & Shortcuts

Commands (via Ctrl+Shift+P)

• 🍅 Start Focus Timer: Begin work session
• ⏹️ Stop Focus Timer: Pause current session
• 🔄 Reset Focus Timer: Reset timer and session count
• ⚙️ Timer Settings: Open settings
• ☕ Support This Extension: Show sponsor info

Keyboard Shortcuts

• Ctrl+Shift+T (Windows/Linux) / Cmd+Shift+T (Mac): Toggle timer (start/stop)

Smart Context: The shortcut automatically switches between start/stop based on timer state.

🎯 Use Cases

Deep Work Sessions

Perfect for focused coding, debugging, or learning new technologies. The timer keeps you accountable without being intrusive.

Meeting Breaks

Use between back-to-back meetings to ensure you get proper breaks and maintain energy throughout the day.

Learning & Research

Great for studying documentation, tutorials, or planning architecture. Breaks help process and retain information.

Pair Programming

Keep sessions time-boxed and ensure both developers get regular breaks to stay fresh and focused.

Code Reviews

Maintain focus during lengthy code review sessions while ensuring you don't burn out.

💡 Tips for Maximum Productivity

Customize for Your Flow

• Shorter sessions (15-20 min) for complex debugging
• Longer sessions (30-45 min) for feature development
• Micro-breaks (2-3 min) for quick mental resets

Combine with Other Tools

• Turn off notifications during focus sessions
• Use VS Code's Zen Mode for distraction-free coding
• Close unnecessary browser tabs and apps

Listen to Your Body

• Adjust break lengths based on your energy levels
• Use long breaks for movement and exercise
• Stay hydrated and maintain good posture

🛠️ Development

Building from Source

1. Clone this repository
2. Install dependencies:

   npm install
   

3. Compile TypeScript:

   npm run compile
   

4. Test the extension:
   • Press F5 in VS Code to launch Extension Development Host
   • Look for the 🍅 in the status bar

Project Structure

minimalist-focus-timer/
├── src/
│   └── extension.ts          # Main timer logic
├── images/                   # Extension icon
├── package.json             # Extension manifest
├── tsconfig.json           # TypeScript configuration
├── build.ps1               # Build script
└── README.md               # This file

Building VSIX Package

# Install vsce globally
npm install -g vsce

# Package the extension
npm run package

🐛 Troubleshooting

Timer Not Visible

• Check that the status bar is enabled: View > Appearance > Status Bar
• Restart VS Code if the extension was just installed

Timer Resets on VS Code Restart

• This is by design for safety - running timers don't persist across restarts
• Session counts and settings are preserved

Notifications Not Showing

• Check focusTimer.showNotifications setting
• Verify VS Code has notification permissions in your OS
• Some systems may block background notifications

Keyboard Shortcut Conflicts

• The default Ctrl+Shift+T might conflict with other extensions
• Customize shortcuts in File > Preferences > Keyboard Shortcuts
• Search for "Focus Timer" to modify bindings

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Issues and enhancement requests are welcome! The goal is to keep this extension minimal while maximizing productivity impact.

☕ Like This Extension?

Support its development and keep it free for everyone:

Your support helps:

• ✨ Keep the extension free for everyone
• 🚀 Fund new features and improvements
• 🐛 Fix bugs and maintain compatibility
• 📚 Create better documentation

Stay focused, stay productive! 🍅✨

Note: This extension is designed for end users to install directly from the VS Code Marketplace. No building or compilation required!