🍅 Pomodoro CLI

A CLI-driven Pomodoro timer for developers to maintain healthy work-break cycles.

✨ Features

• 🎯 Focused Work Sessions: 25-minute timer with real-time countdown display
• ⏸️ Smart Controls: Pause, resume, and stop functionality
• 📊 Progress Tracking: Daily statistics and session history
• 🔔 Break Enforcement: System-level interventions to ensure you take breaks
• ⚡ Fast & Lightweight: Optimized CLI with minimal dependencies
• 🌍 Cross-Platform: Works on macOS, Linux, and Windows

🚀 Installation

NPM (Recommended)

npm install -g @moazzam/pomodoro-cli

Development Install

git clone https://github.com/moazzam-ahmed/pomodoro-cli.git
cd pomodoro-cli
npm install
npm link

🎮 Usage

Basic Commands

Start a Pomodoro Session

pomodoro start                    # 25-minute session (default)
pomodoro start --duration 30     # Custom duration
pomodoro start -d 45             # Short flag

Control Your Session

pomodoro pause                    # Pause current session
pomodoro resume                   # Resume paused session
pomodoro stop                     # Stop current session

View Statistics

pomodoro stats                    # Today's productivity stats

Get Help

pomodoro --help                   # Show all commands
pomodoro start --help             # Command-specific help

🖥️ Real-Time Display

When you start a session, you'll see a beautiful real-time countdown:

🍅 Work Session
    25:00
████████████████████ 100%

Started at 2:30:15 PM

📋 Examples

Quick 15-minute focus session

pomodoro start -d 15

Check your daily progress

pomodoro stats

Output:

📊 Daily Statistics
==================
Date: Sun Jul 13 2025
Completed sessions: 4
Total sessions: 5
Total focus time: 100 minutes
Average session: 25 minutes
Completion rate: 80%

⚙️ Configuration

The app automatically creates configuration files in platform-appropriate locations:

• macOS: ~/Library/Preferences/pomodoro-cli/
• Linux: ~/.config/pomodoro-cli/
• Windows: %APPDATA%/pomodoro-cli/

Custom Durations

Supports work sessions from 1 to 240 minutes (4 hours).

🔧 Break Enforcement

The Pomodoro technique requires taking breaks! This CLI enforces breaks through:

• Desktop Notifications: System notifications when sessions complete
• Visual Feedback: Clear completion status and next steps
• Session Tracking: Monitors break compliance in statistics

Note: Advanced break enforcement features (screen overlay, input blocking) are planned for future releases.

🏗️ Architecture

Built with modern Node.js technologies:

• CLI Framework: Commander.js for argument parsing
• UI Rendering: Ink + React for real-time terminal display
• Configuration: Cross-platform config management with Conf
• Notifications: node-notifier for desktop alerts

🤝 Contributing

We welcome contributions! Please see our development workflow:

1. Fork & Clone: Fork the repository and clone locally
2. Install Dependencies: npm install
3. Run Tests: npm test
4. Lint Code: npm run lint
5. Submit PR: Create pull request with clear description

Development Commands

npm start                         # Run CLI in development
npm test                          # Run test suite
npm run lint                      # Check code quality
npm run dev                       # Watch mode for development

📚 Resources

• Pomodoro Technique: Learn more about the Pomodoro Technique
• Health Benefits: Regular breaks reduce eye strain, improve posture, and boost productivity
• Developer Wellness: Maintaining healthy work habits for sustainable coding

🐛 Troubleshooting

Common Issues

CLI command not found after installation

npm install -g @moazzam/pomodoro-cli
# Ensure ~/.npm-global/bin is in your PATH

Notifications not working

• Ensure system notifications are enabled
• Check notification permissions for terminal applications

Timer appears frozen

• Press Ctrl+C to safely exit
• Restart the session with pomodoro start

Getting Help

• GitHub Issues: Report bugs and request features
• Documentation: This README and --help commands
• Support: Community support via GitHub Discussions

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Francesco Cirillo: Creator of the Pomodoro Technique
• Open Source Community: For the excellent libraries that make this possible
• Developer Wellness Movement: For promoting healthy coding practices

Stay focused, stay healthy! 🍅✨