🍅 PowerToys Run: Pomodoro Plugin

⏱️ Pomodoro for PowerToys Run ⏱️

Manage your productivity sessions directly from PowerToys Run

📋 Table of Contents

• 📋 Overview
• ⚡ Easy Install
• ✨ Features
• 🎬 Demo Gallery
• 🚀 Installation
• 🔧 Usage
• 📁 Data Storage
• 🛠️ Building from Source
• 📊 Project Structure
• 🤝 Contributing
• ❓ FAQ
• ✨ Why You'll Love Pomodoro Plugin
• 📄 License
• 🙏 Acknowledgements
• 🛠️ Implementation Details
• 🚶‍♂️ My Pomodoro Journey

📋 Overview

Pomodoro is a plugin for Microsoft PowerToys Run that brings the popular Pomodoro Technique to your keyboard. Simply type pomodoro followed by a command like start, pause, or status to manage your productivity sessions directly from your PowerToys Run interface.

⚡ Easy Install

Quick Installation Steps:
1. Download using the button above
2. Extract to %LOCALAPPDATA%\Microsoft\PowerToys\PowerToys Run\Plugins\
3. Restart PowerToys
4. Start using with Alt+Space then type pomodoro

✨ Features

• ⏱️ Start, Pause, and Reset Pomodoro Sessions - Manage your work sessions with simple commands
• 🍅 Visual Countdown - See time remaining in your current session
• 🔔 End-of-Session Alerts - Get notified when your session ends with sound or visual cues
• 🌙 Break Management - Automatically switch between work sessions and breaks
• ⚙️ Configurable Session Length - Customize work and break durations to fit your workflow

🎬 Demo Gallery

🍅 Start a Pomodoro Session

Simply type pomodoro start to begin a focused work session

🚀 Installation

📋 Prerequisites

• Microsoft PowerToys installed
• Windows 10 or later

📥 Installation Steps

1. Download the latest release from the Releases page
2. Extract the ZIP file to:

   %LOCALAPPDATA%\Microsoft\PowerToys\PowerToys Run\Plugins\
   

3. Restart PowerToys
4. Open PowerToys Run and type pomodoro to access the plugin

🔧 Usage

1. Open PowerToys Run (default: Alt + Space)
2. Use the following commands:

Command	Description	Example
pomodoro	Show Pomodoro instructions	pomodoro
pomodoro start	Start a new Pomodoro session	pomodoro start
pomodoro pause	Pause the current timer	pomodoro pause
pomodoro resume	Resume a paused timer	pomodoro resume
pomodoro stop	Stop and reset the timer	pomodoro stop
pomodoro status	Show remaining time and state	pomodoro status
pomodoro break	Start a short break	pomodoro break
pomodoro longbreak	Start a long break	pomodoro longbreak

🎯 Quick Tips

• Press Enter on a command to execute it
• Right-click on a command for additional options
• Customize plugin settings in PowerToys Settings
• Long breaks automatically trigger after a configurable number of completed Pomodoros

📁 Data Storage

The Pomodoro plugin stores the following settings locally:

• Session length preferences (Pomodoro, short break, long break)
• Sound notification preference (enabled/disabled)
• Auto-start next session preference (enabled/disabled)
• Completed session history and statistics

All settings are stored securely in the PowerToys settings file.

🛠️ Building from Source

1. Clone the repository:

   git clone https://github.com/ruslanlap/PowerToysRun-Pomodoro.git
   

2. Open the solution in Visual Studio 2022 or later

3. Build the solution:

   dotnet build Pomodoro/Pomodoro.sln
   

4. Run the build-and-zip script to create installation packages:

   ./build-and-zip.sh
   

📊 Project Structure

Pomodoro/
├── Community.PowerToys.Run.Plugin.Pomodoro/
│   ├── Images/                  # Plugin icons and animations
│   ├── Sounds/                  # Sound effects
│   ├── Main.cs                  # Main plugin logic
│   ├── PomodoroResultWindow.xaml # Pomodoro timer window
│   ├── plugin.json             # Plugin metadata
│   └── ...
├── Services/
│   ├── TickCounterApiService.cs # Timer service
│   ├── SoundService.cs          # Sound notification service
├── Models/
│   ├── PomodoroSession.cs       # Session data model
│   ├── PomodoroSettings.cs      # Settings data model
└── Pomodoro.sln                # Solution file

🤝 Contributing

Contributions are welcome! Here's how you can help:

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 the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Please make sure to update tests as appropriate.

Contributors

• ruslanlap - Project creator and maintainer

❓ FAQ

How do I customize the Pomodoro session length?

Open PowerToys Settings, navigate to PowerToys Run > Plugins > Pomodoro, and adjust the "Pomodoro length (minutes)" setting.

Can I disable sound notifications?

Yes, open PowerToys Settings, navigate to PowerToys Run > Plugins > Pomodoro, and toggle the "Play sound notifications" option.

What happens when a Pomodoro session ends?

By default, you'll receive a notification. If you've enabled "Auto-start next phase," the plugin will automatically start a short break after a work session, or a work session after a break.

How many Pomodoros before a long break?

By default, a long break occurs after 4 completed Pomodoro sessions. This can be customized in the settings.

Can I view my productivity history?

Yes, this feature is available in the plugin. Your completed sessions are tracked and can be viewed through the plugin interface.

✨ Why You'll Love Pomodoro Plugin

• Helps Maintain Focus: Structure your work with dedicated focus periods
• Encourages Healthy Break Patterns: Reminds you to take regular breaks
• Tracks Daily Performance: Monitor your productivity patterns
• Keyboard-Centric: Perfect for keyboard power users
• Customizable: Set your preferred session lengths and notification settings
• Fast: Instant access to timer controls
• Beautiful: Clean, modern UI that matches PowerToys style
• Resource-Efficient: Lightweight with minimal system impact

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgements

• Microsoft PowerToys team for the amazing launcher
• All contributors who have helped improve this plugin
• The Pomodoro Technique® by Francesco Cirillo for the time management method

🛠️ Implementation Details

The Pomodoro plugin is built using:

• C# and .NET
• WPF for the UI components
• System.Timers.Timer for countdown functionality
• Windows notification API for alerts
• Task-based asynchronous pattern for non-blocking operations

The plugin implements several PowerToys Run interfaces:

• IPlugin - Core plugin functionality
• IDelayedExecutionPlugin - Support for delayed execution
• IContextMenu - Right-click context menu
• IDisposable - Resource cleanup
• ISettingProvider - Settings management

Roadmap

• Custom notification sounds
• Weekly productivity analytics
• Task labeling for Pomodoro sessions

🚶‍♂️ My Pomodoro Journey

I created this plugin because the Pomodoro Technique transformed my own productivity. As a developer juggling multiple projects, I found myself constantly distracted and struggling to maintain focus for extended periods. That's when I discovered the power of structured work intervals.

The problem? I needed a tool that integrated seamlessly with my workflow - no separate apps to launch or browser tabs to keep open. PowerToys Run was already part of my daily routine, so building a Pomodoro plugin felt like the perfect solution.

This plugin represents hundreds of hours of focused work (ironically, managed using the Pomodoro Technique itself!). It's designed by a developer, for developers, with the features I personally needed to stay productive:

• Zero Friction: Two keystrokes (Alt+Space) and I'm managing my time
• Minimal Interruption: Notifications that don't break concentration
• Rhythm Building: The consistent work/break pattern helped me develop better focus habits

I hope this plugin helps you as much as the technique has helped me. Happy focusing! 🍅

With love from ruslanlap 🌟