Tomato Timer is a cross-platform desktop Pomodoro timer built with Electron and React. It features an always-on-top transparent overlay, customizable presets, and focus/break cycle tracking to help maintain productivity through proven time management techniques.
- Precise Countdown - Hours, minutes, and seconds with second-level accuracy
- 11 Quick Presets - 1m, 3m, 5m, 10m, 15m, 20m, 25m, 30m, 45m, 1h, 90m for common work intervals
- Pomodoro Mode - Traditional 25/5 work/break cycles with long break every 4th session
- Custom Duration - Set any timer length from 1 minute to 99 hours
- Manual Controls - Focus, Short Break, Long Break, Next session buttons
- Always-on-Top Overlay - Transparent window that stays visible above all applications
- Click-through Mode - Toggle with
Ctrl/Cmd + 6to interact with windows beneath the timer - Frameless Design - Clean, borderless window with custom controls
- System Tray Integration - Background operation with quick access menu
- Cross-Platform - Consistent experience on Windows, macOS, and Linux
- Auto-queue Next Session - Automatically start next Pomodoro cycle (toggleable)
- Completed Focus Counter - Visual tracking of accomplished focus blocks
- Session History - Track your productivity patterns over time
- Sound Notifications - Audio cues for session start/end (optional)
- Visual Indicators - Color-coded states for focus vs break periods
- Electron + React - Modern desktop framework with component-based UI
- TypeScript - End-to-end type safety for enhanced reliability
- Local Storage - Persistent preferences and session data
- Global Shortcuts - System-wide hotkeys for timer control
- Automatic Updates - Ready for electron-updater implementation
- Accessibility - Keyboard navigation and screen reader friendly
- Electron - Cross-platform desktop application framework
- React - Component-based UI library
- TypeScript - Static typing for JavaScript
- React State - useState and useReducer for component state
- localStorage - Persistent user preferences and settings
- Electron Storage - app.getPath('userData') for application data
- electron-builder - Packaging and distribution tool
- GitHub Actions - Automated build and release pipeline
- Platform Specific - NSIS (Windows), dmg (macOS), AppImage (Linux)
┌─────────────────────────────┐
│ Main Process │
│ (Electron/BrowserWindow) │
├─────────────────────────────┤
│ │ Preload Script (Context) │
│ ├─────────────────────────┤ │
│ │ Renderer Process │ │
│ │ (React + TypeScript) │ │
│ │ ├─────────────────────┤ │ │
│ │ │ Timer Logic │ │ │
│ │ │ UI Components │ │ │
│ │ │ Settings Panel │ │ │
│ │ ├─────────────────────┤ │ │
│ │ │ Global Shortcuts │ │ │
│ │ │ System Tray Menu │ │ │
│ │ └─────────────────────┘ │ │
│ └─────────────────────────┘ │
└─────────────────────────────┘
│
▼
┌─────────────────┐
│ User Data Dir │
│ (localStorage, │
│ settings.json) │
└─────────────────┘
# Clone repository
git clone https://github.com/howardsun-dev/tomato-timer.git
cd tomato-timer
# Install dependencies
npm install
# Start in development mode
npm start
# Opens Electron window with React devtoolsDownload latest release from GitHub Releases:
Windows:
- Download the .exe installer
- Run and follow installation wizard
- Launch from Start menu or desktop shortcut
macOS:
- Download the .dmg file
- Open and drag Tomato Timer to Applications folder
- Launch from Applications or Launchpad
Linux:
- Download the AppImage
- Make executable:
chmod +x Tomato-Timer-*.AppImage - Run:
./Tomato-Timer-*.AppImage - (Optional) Integrate with desktop menu using AppImage launcher
# Linting
npm run lint
# Type checking
npm run typecheck
# Format code
npm run format
# Run tests (when implemented)
npm test- Software Developers - Maintain focus during coding sessions
- Writers & Creators - Pomodoro technique for writing sessions
- Students - Study sessions with built-in break reminders
- Professionals - Time blocking and meeting preparation
- Anyone seeking to improve time management and productivity
This project showcases proficiency in:
- Electron Development - Main/renderer process communication, preload scripts
- React Desktop Applications - Component-based UI with hooks
- TypeScript - End-to-end type safety in desktop context
- Cross-Platform Build - Windows/macOS/Linux packaging and distribution
- User Experience Design - Always-on-top windows, click-through modes
- Productivity Tools - Understanding of time management methodologies
- Desktop Integration - System tray, global shortcuts, notifications
- Persistent Storage - User preferences and application state management
- GitHub Actions CI/CD - Automated build, test, and release workflows
- Improved Focus - Timed intervals create urgency and reduce procrastination
- Regular Breaks - Prevents burnout and maintains mental freshness
- Time Awareness - Makes time tangible and measurable
- Reduced Multitasking - Encourages single-task focus during intervals
- Better Planning - Helps estimate effort for future tasks
- Toggl integration for time tracking export
- Customizable work/break ratios
- Daily/weekly productivity reports
- Ambient sound options (white noise, cafe sounds)
- Mission statement/goals setting per session
- Team mode with shared timers
- Dark/light theme switching
- Keyboard layout customization
- Progress bar visualization within timer display
Issues & Bug Reports: GitHub Issues
Feature Requests: GitHub Discussions
Pull Requests: Welcome! Please follow contribution guidelines
Email: howardsun.swe@gmail.com
Built by Howard Sun — Full-Stack Engineer specializing in Electron, React, and TypeScript desktop applications that enhance productivity and user experience.