🍅 Vibodoro

A simple command-line Pomodoro timer in Python. Stay focused and productive with this minimalist timer that helps you implement the Pomodoro Technique right from your terminal.

✨ Features

• 🎯 Focused Sessions: Default 25-minute Pomodoro sessions with customizable duration
• 📊 Visual Progress: Real-time progress bar showing elapsed time and remaining duration
• ⏸️ Pause/Resume: Spacebar to pause and resume your sessions
• 🎮 Simple Controls: Intuitive keyboard controls (Space to pause, Ctrl+C to quit)
• 🎨 Fun UI: Clean, colorful progress display with emojis
• 🚀 Standalone: Install globally with uvx for system-wide access

📋 Requirements

• Python 3.13+
• uv package manager

🚀 Quick Start

Option 1: Install Globally with uv tool (Recommended)

Install and run Vibodoro anywhere on your system:

# Install uv (if you haven't already)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Vibodoro globally from source
git clone <repository-url>
cd vibodoro
uv tool install --from . vibodoro

Once installed, you can run Vibodoro from anywhere:

# Run from anywhere in your system
vibodoro --help
vibodoro --minutes 15

Option 2: Local Development Setup

For development or local use:

git clone <repository-url>
cd vibodoro
uv sync
uv run vibodoro --minutes 25

📖 Usage

Standalone Commands (after uv tool installation)

# Start a 25-minute Pomodoro (default)
vibodoro

# Start a custom duration session  
vibodoro --minutes 30

# Show help
vibodoro --help

Local Development Commands

# Start a 25-minute Pomodoro (default)
uv run vibodoro

# Start a custom duration session
uv run vibodoro --minutes 30

# Show help
uv run vibodoro --help

During a Session

• Press SPACE to pause/resume the timer
• Press Ctrl+C to quit the session
• The progress bar shows:
  • Current progress percentage
  • Visual progress bar
  • Elapsed time / Total time
  • Remaining time in MM:SS format

Example Session

🍅 Starting 25 minute Pomodoro session
Press SPACE to pause/resume • Press Ctrl+C to quit

🍅 Pomodoro (24:30): 2%|▎                    | 0:00:30/0:25:00

When paused:

Paused -- press Space to resume.

On completion:

🎉 Pomodoro session completed! Time for a break!

🛠️ Development Setup

Prerequisites

• Python 3.13+
• uv package manager

Setup Development Environment

# Clone the repository
git clone <repository-url>
cd vibodoro

# Install dependencies (including test dependencies)
uv sync --extra test

# Run the application in development
uv run vibodoro --minutes 1

Project Structure

vibodoro/
├── src/
│   └── vibodoro/
│       ├── __init__.py      # Package initialization
│       └── main.py          # Main application code
├── test_main.py             # Pytest test suite
├── pyproject.toml           # Project configuration and dependencies
├── dist/                    # Built packages (after uv build)
├── docs/
│   └── specs.md             # Technical specifications
└── README.md               # This file

Building the Package

# Build source distribution and wheel
uv build

# Install globally from built wheel
uvx --from ./dist/vibodoro-0.1.0-py3-none-any.whl vibodoro

# Test the standalone installation
vibodoro --help

🧪 Testing

We use pytest for testing. All tests are located in test_main.py.

# Install test dependencies
uv sync --extra test

# Run all tests
uv run pytest test_main.py

# Run tests with verbose output
uv run pytest test_main.py -v

# Run specific test
uv run pytest test_main.py::TestPomodoroTimer::test_timer_initialization -v

Test Coverage

The test suite includes:

• Timer initialization and configuration
• Pause/resume functionality
• CLI argument parsing
• Terminal setup and restoration
• Error handling
• Parametrized tests for various durations

📦 Dependencies

Runtime Dependencies

• click (≥8.0.0) - Command-line interface
• tqdm (≥4.60.0) - Progress bar display

Development Dependencies

• pytest (≥7.0.0) - Testing framework

🎯 The Pomodoro Technique

The Pomodoro Technique is a time management method:

1. 🍅 Work: Focus on a task for 25 minutes
2. ☕ Short Break: Take a 5-minute break
3. 🔄 Repeat: After 4 pomodoros, take a longer break (15-30 minutes)

Vibodoro helps you track the work sessions - use your preferred timer or app for breaks!

🤝 Contributing

Contributions are welcome! Please feel free to:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (uv run pytest test_main.py)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📜 License

This project is open source and available under the MIT License.

🙏 Acknowledgments

• Inspired by the Pomodoro Technique by Francesco Cirillo
• Built with ❤️ using Python, Click, and tqdm

Happy focusing! 🍅✨