- 📋 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
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.
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
- ⏱️ 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
- 🪟 Resizable & Minimizable Timer Window - Resize the timer window with the corner grip, minimize it to the taskbar, and it remembers your preferred size and position between sessions
- 🎵 Media Control - Automatically play/pause media (Spotify, YouTube, etc.) when sessions start and end
- 🪝 CLI Hooks - Run arbitrary CLI commands on timer events (start, end, pause, resume, stop), including dedicated break start/end hooks
- Microsoft PowerToys installed
- Windows 10 or later
- Download the latest release from the Releases page
- Extract the ZIP file to:
%LOCALAPPDATA%\Microsoft\PowerToys\PowerToys Run\Plugins\ - Restart PowerToys
- Open PowerToys Run and type
pomodoroto access the plugin
- Open PowerToys Run (default: Alt + Space)
- 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 |
- 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
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.
-
Clone the repository:
git clone https://github.com/ruslanlap/PowerToysRun-Pomodoro.git -
Open the solution in Visual Studio 2022 or later
-
Build the solution:
dotnet build Pomodoro/Pomodoro.sln -
Run the build-and-zip script to create installation packages:
./build-and-zip.sh
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
Contributions are welcome! Here's how you can help:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
This project uses release-please bot for automated versioning and releases. Use Conventional Commits format:
| Commit type | Bump | Example |
|---|---|---|
fix: |
Patch (1.0.0 → 1.0.1) | fix: correct timer display |
feat: |
Minor (1.0.0 → 1.1.0) | feat: add break reminders |
BREAKING CHANGE: |
Major (1.0.0 → 2.0.0) | feat!: new config format |
When you push to master, the bot opens a "release PR" with a changelog and version bump. Merge it to publish a new release automatically.
Please make sure to update tests as appropriate.
- ruslanlap - Project creator and maintainer
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.
The plugin can automatically control media playback (play/pause) when your focus sessions start and end. This works with any application that responds to Windows media keys — Spotify, YouTube (in your browser), Windows Media Player, foobar2000, and more.
Open PowerToys Settings → PowerToys Run → Plugins → Pomodoro:
| Setting | Description |
|---|---|
| ▶ Play media on session start | Toggles play/pause when a Pomodoro (focus) session starts |
| ⏸ Pause media on session end | Toggles play/pause when a Pomodoro (focus) session ends |
Note: Media control only triggers for Pomodoro (focus) sessions, not for breaks. This way your music starts when you begin working and pauses when your focus session is over — exactly the behavior described in issue #2.
For power users, the plugin can run arbitrary CLI commands on timer lifecycle events. This enables integrations like:
- 🏠 Smart home: Turn lights on during breaks, dim them during focus
- 📊 Time tracking: Log sessions to Toggl, Clockify, or a spreadsheet
- 🔔 Notifications: Send a Slack/Discord/Teams message when sessions end
- 🎵 Custom media control: Use
nircmdor AutoHotkey for advanced media management
| Event | Trigger | Setting Key |
|---|---|---|
| Pomodoro Start | When a Pomodoro focus session begins | HookOnPomodoroStart |
| Pomodoro End | When a Pomodoro focus session completes | HookOnPomodoroEnd |
| Break Start | When any break (short or long) begins | HookOnBreakStart |
| Break End | When any break completes | HookOnBreakEnd |
| Pause | When the timer is paused | HookOnPause |
| Resume | When the timer is resumed | HookOnResume |
| Stop | When the timer is manually stopped | HookOnStop |
Command strings support the following tokens, which are replaced with event details before execution:
| Token | Description | Example value |
|---|---|---|
{event} |
Event name | start, end, pause, resume, stop |
{type} |
Session type | Pomodoro, Short Break, Long Break |
{minutes} |
Session length in minutes | 25 |
# On break start — turn lights on
HookOnBreakStart: hue lights on --brightness 100
# On Pomodoro start — dim lights for focus
HookOnPomodoroStart: hue lights dim --brightness 30
# On Pomodoro start — start a Toggl timer
HookOnPomodoroStart: toggl start --description "Pomodoro ({minutes} min)"
# On Pomodoro end — stop the Toggl timer
HookOnPomodoroEnd: toggl stop
# On Pomodoro end
HookOnPomodoroEnd: powershell -Command "New-BurntToastNotification -Text 'Pomodoro Complete!', 'Time for a break.'"
# On break start — play a custom sound
HookOnBreakStart: powershell -Command "(New-Object Media.SoundPlayer 'C:\Sounds\chime.wav').PlaySync()"
Note: Hooks are executed via
cmd.exe /c <command>in a hidden window, fire-and-forget (the plugin does not wait for them to complete).
- 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
This project is licensed under the MIT License - see the LICENSE file for details.
- 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
The Pomodoro plugin is built using:
- C# and .NET 9
- 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 functionalityIDelayedExecutionPlugin- Support for delayed executionIContextMenu- Right-click context menuIDisposable- Resource cleanupISettingProvider- Settings management
- Media control (play/pause on session start/end) — #2
- CLI hooks for custom integrations — #2
- Custom notification sounds
- Weekly productivity analytics
- Task labeling for Pomodoro sessions
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 🌟