Skip to content

README.md

Latest commit

 

History

History
299 lines (220 loc) · 7.91 KB

README.md

File metadata and controls

299 lines (220 loc) · 7.91 KB

CLIfficiency 🍅

npm version License: MIT TypeScript Node.js

A beautiful, feature-rich CLI Pomodoro timer with customizable presets, desktop notifications, and an elegant progress bar interface. Boost your productivity with the proven Pomodoro Technique right from your terminal.

✨ Features

  • 🎯 Classic Pomodoro Technique: Traditional 25/5/15 minute work/break cycles
  • 🔧 Fully Customizable: Adjust work, short break, long break durations and session counts
  • 📋 Smart Presets: Quick-start with fast, focus, or default configurations
  • 🎨 Beautiful Progress Bar: Colorful, animated progress indicator with time remaining
  • 🔔 Desktop Notifications: Native OS notifications with custom sounds and images
  • 💡 Session Tracking: Visual session counter to track your productivity streaks
  • 🎵 Custom Sound Alerts: Distinctive notification sounds for phase transitions
  • 🖥️ Cross-Platform: Works on macOS, Windows, and Linux
  • ⚡ Lightweight: Fast startup and minimal resource usage

🚀 Quick Start

Installation

Install globally via npm:

npm install -g clifficiency

Basic Usage

Start a default Pomodoro session:

cliff

That's it! CLIfficiency will start a 25-minute work session, followed by 5-minute breaks, with a 15-minute long break every 4 sessions.

📖 Usage Guide

Command Line Options

cliff [options]

Options

Option Short Description Example
--work <minutes> -w Set work duration in minutes cliff -w 30
--short <minutes> -s Set short break duration in minutes cliff -s 10
--long <minutes> -l Set long break duration in minutes cliff -l 20
--sessions <number> -n Sessions before long break cliff -n 3
--preset <name> -p Use a predefined preset cliff -p focus
--version -V Show version number cliff --version
--help -h Display help information cliff --help

Presets

CLIfficiency comes with three built-in presets:

Default Preset

cliff -p default
# or simply
cliff
  • Work: 25 minutes
  • Short Break: 5 minutes
  • Long Break: 15 minutes
  • Sessions: 4 (classic Pomodoro)

Focus Preset

cliff -p focus
  • Work: 50 minutes
  • Short Break: 10 minutes
  • Long Break: 30 minutes
  • Sessions: 4 (deep work sessions)

Fast Preset

cliff -p fast
  • Work: 1 minute
  • Short Break: 1 minute
  • Long Break: 2 minutes
  • Sessions: 2 (for testing/demo)

Custom Configurations

Override any preset or create your own timing:

# Custom work and break times
cliff -w 45 -s 15 -l 25

# Custom session count with focus preset
cliff -p focus -n 3

# Completely custom configuration
cliff -w 30 -s 7 -l 20 -n 5

📊 Interface Overview

When running, CLIfficiency displays:

Work █████████████████████████████████████████████ 100% | (#2) 25:00 time remaining
  • Phase Name: Current activity (Work, Short Break, Long Break)
  • Progress Bar: Visual progress with completion percentage
  • Session Counter: Current session number (#2)
  • Time Remaining: Countdown timer in MM:SS format

🔔 Notifications

CLIfficiency sends native desktop notifications for each phase transition:

Work Phase

  • Title: "¡Hora de trabajar! 💻"
  • Message: "Enfócate por unos minutos más."

Short Break

  • Title: "Tómate un respiro ☕"
  • Message: "Estira un poco o toma agua."

Long Break

  • Title: "¡Descanso largo! 🧘"
  • Message: "Tómate tu merecido descanso."

Each notification includes:

  • Custom CLIfficiency sound alert
  • Application icon
  • Automatic dismissal (non-blocking)

🎵 Sound Configuration

CLIfficiency automatically installs a custom notification sound (CLIfficiency_noti.wav) to your system's sound library. The sound is automatically copied to:

  • macOS: ~/Library/Sounds/
  • Windows: System sounds directory
  • Linux: User sound directory

🛠️ Technical Details

Requirements

  • Node.js: 14.0.0 or higher
  • npm: 6.0.0 or higher
  • Operating System: macOS, Windows 10+, or Linux

Dependencies

  • commander: CLI argument parsing
  • cli-progress: Beautiful progress bars
  • ansi-colors: Terminal color support
  • node-notifier: Cross-platform notifications
  • TypeScript: Type safety and modern JavaScript features

File Structure

clifficiency/
├── dist/                 # Compiled JavaScript
├── src/
│   ├── core/
│   │   └── PomodoroTimer.ts   # Core timer logic
│   ├── ui/
│   │   └── ProgressBar.ts     # Progress bar interface
│   ├── cli.ts                 # Command line interface
│   ├── presets.ts             # Timer presets
│   └── index.ts               # Main application entry
├── assets/
│   ├── sounds/               # Notification sounds
│   └── images/               # Application icons
└── package.json

🤝 Contributing

We welcome contributions! Here's how you can help:

Development Setup

  1. Clone the repository:

    git clone https://github.com/JosueIsOffline/CLIfficiency.git
cd CLIfficiency

  2. Install dependencies:

    npm install

  3. Run in development mode:

    npm run dev

  4. Build the project:

    npm run build

Testing

Test your changes with the fast preset:

npm run dev -- -p fast

This runs 1-minute cycles for quick testing.

Pull Request Guidelines

  • Fork the repository and create a feature branch
  • Write clear, descriptive commit messages
  • Test your changes thoroughly
  • Update documentation if needed
  • Submit a pull request with a detailed description

📝 Examples

Daily Productivity Session

# Standard Pomodoro for focused work
cliff -p default

Deep Work Session

# Longer focus periods for complex tasks
cliff -p focus

Custom Study Session

# 40-minute study periods with longer breaks
cliff -w 40 -s 10 -l 25 -n 3

Quick Meeting Timer

# 15-minute focused sessions
cliff -w 15 -s 5 -l 10 -n 2

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Josué R. Hernández Montero

🐛 Bug Reports & Feature Requests

Found a bug or have a feature request? Please create an issue on our GitHub Issues page.

When reporting bugs, please include:

  • Your operating system and version
  • Node.js version (node --version)
  • CLIfficiency version (cliff --version)
  • Steps to reproduce the issue
  • Expected vs actual behavior

🔗 Links

📊 Changelog

v1.0.0

  • Initial release
  • Core Pomodoro timer functionality
  • Three built-in presets (default, focus, fast)
  • Desktop notifications with custom sounds
  • Colorful progress bar interface
  • Cross-platform compatibility
  • Full TypeScript implementation

Happy Productivity! 🍅✨

Made with ❤️ using TypeScript and the Pomodoro Technique