npm package: @moazzam-qureshi/pomodoro-cli
Description: A CLI Pomodoro timer for developers to maintain healthy work-break cycles
Author: Claude Code Assistant
Latest version: 1.0.1

# 🍅 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)
```bash
npm install -g @moazzam/pomodoro-cli
```

### Development Install
```bash
git clone https://github.com/moazzam-ahmed/pomodoro-cli.git
cd pomodoro-cli
npm install
npm link
```

## 🎮 Usage

### Basic Commands

#### Start a Pomodoro Session
```bash
pomodoro start                    # 25-minute session (default)
pomodoro start --duration 30     # Custom duration
pomodoro start -d 45             # Short flag
```

#### Control Your Session
```bash
pomodoro pause                    # Pause current session
pomodoro resume                   # Resume paused session
pomodoro stop                     # Stop current session
```

#### View Statistics
```bash
pomodoro stats                    # Today's productivity stats
```

#### Get Help
```bash
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
```bash
pomodoro start -d 15
```

### Check your daily progress
```bash
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
```bash
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](https://en.wikipedia.org/wiki/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**
```bash
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](https://github.com/moazzam-ahmed/pomodoro-cli/issues)
- **Documentation**: This README and `--help` commands
- **Support**: Community support via GitHub Discussions

## 📄 License

MIT License - see [LICENSE](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!** 🍅✨