Thanks to visit codestin.com
Credit goes to github.com

Skip to content

ethan-k/pomodoro-cli

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

15 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸ… Pomodoro CLI

A minimalist macOS CLI Pomodoro timer built in Go with advanced features for productivity tracking.

✨ Features

Core Timer Functionality

  • Start Pomodoro Sessions - Focus work sessions with customizable durations and descriptions
  • Break Timers - Short and long break management
  • Pause/Resume - Pause sessions temporarily and resume where you left off
  • Session Cancellation - End sessions early when needed

Audio & Notifications

  • Audio Alerts πŸ”Š - Sound notifications when sessions complete (configurable)
  • Desktop Notifications - Native OS notifications with session details
  • Silent Mode - Disable audio for individual sessions with --silent flag

Session Management

  • Continuous Mode - Stay in the program after session completion for seamless workflow
  • Session History - Track all your completed pomodoros and breaks
  • Tags & Organization - Organize sessions with custom tags
  • Goal Tracking - Set and monitor daily/weekly pomodoro targets

Advanced Features

  • Progress Visualization - Beautiful terminal UI with animated progress bars
  • Multiple Export Formats - JSON and Open Pomodoro Format (OPF) support
  • Flexible Configuration - YAML-based configuration with hooks support
  • Input Validation - Smart validation and sanitization of user inputs

πŸš€ Quick Start

Installation

Pre-built Binaries (Recommended)

Download the latest release for your platform from GitHub Releases.

macOS:

# Intel Macs
curl -L -o pomodoro https://github.com/ethan-k/pomodoro-cli/releases/latest/download/pomodoro-darwin-amd64
# Apple Silicon Macs  
curl -L -o pomodoro https://github.com/ethan-k/pomodoro-cli/releases/latest/download/pomodoro-darwin-arm64

chmod +x pomodoro
sudo mv pomodoro /usr/local/bin/

Linux:

# x86_64
curl -L -o pomodoro https://github.com/ethan-k/pomodoro-cli/releases/latest/download/pomodoro-linux-amd64
# ARM64
curl -L -o pomodoro https://github.com/ethan-k/pomodoro-cli/releases/latest/download/pomodoro-linux-arm64

chmod +x pomodoro
sudo mv pomodoro /usr/local/bin/

Windows: Download the appropriate .exe file from the releases page and add it to your PATH.

Go Install (Latest Version)

go install github.com/ethan-k/pomodoro-cli@latest

Build from Source

git clone https://github.com/ethan-k/pomodoro-cli
cd pomodoro-cli
make build
make install

Verify Installation

pomodoro --version

Basic Usage

# Start a 25-minute pomodoro
pomodoro start "Fix authentication bug"

# Start with custom duration and tags
pomodoro start "Code review" --duration 50m --tags coding,review

# Start with continuous mode (stay in program after completion)
pomodoro start "Deep work" --continuous

# Start in silent mode (no audio alerts)
pomodoro start "Meeting focus" --silent

# Take a break
pomodoro break 5m --wait

# Pause current session
pomodoro pause

# Resume paused session
pomodoro resume --wait

# Check status
pomodoro status

# View session history
pomodoro history --today
pomodoro history --week
pomodoro history --output json

πŸ“– Commands Reference

Session Commands

Command Description Examples
start Start a pomodoro session pomodoro start "Task name"
break Start a break timer pomodoro break 10m
pause Pause active session pomodoro pause
resume Resume paused session pomodoro resume --wait
cancel Cancel active session pomodoro cancel
status Show current session status pomodoro status

Data & Analysis

Command Description Examples
history View session history pomodoro history --today
config Manage configuration pomodoro config show

Global Flags

Flag Description Available Commands
--json JSON output format All commands
--silent Disable audio alerts start, break
--continuous Continuous mode start
--wait Show progress bar break, resume, status

βš™οΈ Configuration

Configuration is stored in ~/.config/pomodoro/config.yml:

# Goal settings
goals:
  daily_count: 8      # Target pomodoros per day
  weekly_count: 40    # Target pomodoros per week

# Default durations
defaults:
  pomodoro_duration: "25m"
  break_duration: "5m"
  long_break_duration: "15m"

# Audio settings
audio:
  enabled: true
  volume: 0.5                    # 0.0 to 1.0 (default: quiet)
  custom_sounds_dir: "~/.config/pomodoro/sounds"
  sounds:
    pomodoro_complete: "pomodoro_complete.wav"
    break_complete: "break_complete.wav"
    session_start: "session_start.wav"

# Data storage paths
paths:
  database: "~/.local/share/pomodoro/history.db"
  opf_export: "~/.local/share/pomodoro/exports"

# Hooks for automation
hooks:
  enabled: false
  path: "~/.config/pomodoro/hooks"

Audio Configuration

Built-in Sounds

The Pomodoro CLI includes professional, public domain notification sounds:

  • Pomodoro Complete: "Calm" - Gentle, soothing notification
  • Break Complete: "Polite" - Soft, pleasant tone
  • Session Start: "Glass" - Light, crisp chime

All sounds are:

  • βœ… Public Domain (CC0) - safe for any use, no attribution required
  • πŸ”” Professional quality - hand-crafted notification tones
  • ⚑ Brief & subtle - designed for mobile/desktop notifications
  • πŸ”Š Cross-platform compatible (WAV format)

Custom Sounds

Replace with your own sounds by placing files in ~/.config/pomodoro/sounds/:

audio:
  sounds:
    pomodoro_complete: "my-custom-bell.wav"
    break_complete: "my-custom-chime.mp3"

Volume Control

# Set volume in config file
pomodoro config audio --volume 0.8

πŸ“Š Session History & Analytics

View History

# Today's sessions
pomodoro history --today

# This week's sessions
pomodoro history --week

# Custom date range
pomodoro history --from 2025-01-01 --to 2025-01-31

# Filter by tags
pomodoro history --tags coding,review

# Export formats
pomodoro history --output json > sessions.json
pomodoro history --output opf > sessions-opf.json

Session Data Structure

Each session includes:

  • ID - Unique session identifier
  • Start/End Times - Precise timing data
  • Description - Session description
  • Duration - Planned vs actual duration
  • Tags - Organization labels
  • Type - Pomodoro or break
  • Pause Data - Pause/resume tracking

πŸ”„ Workflow Examples

Classic Pomodoro Technique

# Start 25min work session
pomodoro start "Feature development" --continuous

# After completion, program prompts for next action:
# 1. Start a break (b)
# 2. Start another pomodoro (p) 
# 3. View status (s)
# 4. Quit (q)

Extended Work Sessions

# 50-minute deep work session
pomodoro start "Complex analysis" --duration 50m --tags analysis,research

# Custom break
pomodoro break 15m --wait

Meeting Focus

# Silent mode for meetings
pomodoro start "Team meeting" --duration 1h --silent --tags meeting

πŸ› οΈ Development

Build Commands

make build          # Build for current platform
make build-all      # Build for all platforms
make test           # Run tests
make coverage       # Generate coverage report
make fmt            # Format code
make lint           # Run linter
make install        # Install to $GOPATH/bin

Project Structure

pomodoro-cli/
β”œβ”€β”€ cmd/                    # CLI commands
β”‚   β”œβ”€β”€ start.go           # Pomodoro start command
β”‚   β”œβ”€β”€ break.go           # Break timer command
β”‚   β”œβ”€β”€ pause.go           # Pause session command
β”‚   β”œβ”€β”€ resume.go          # Resume session command
β”‚   β”œβ”€β”€ status.go          # Session status command
β”‚   └── history.go         # History management
β”œβ”€β”€ internal/
β”‚   β”œβ”€β”€ audio/             # Audio notification system
β”‚   β”œβ”€β”€ config/            # Configuration management
β”‚   β”œβ”€β”€ db/                # SQLite database layer
β”‚   β”œβ”€β”€ model/             # Bubble Tea UI models
β”‚   β”œβ”€β”€ notify/            # Notification system
β”‚   └── utils/             # Shared utilities
β”œβ”€β”€ specs/                 # Feature specifications
└── Makefile              # Build automation

πŸ“ˆ Advanced Usage

Automation & Scripting

The JSON output format makes scripting easy:

# Check if session is active
if pomodoro status --json | jq -r '.active' == "true"; then
    echo "Session in progress"
fi

# Get today's pomodoro count
count=$(pomodoro history --today --output json | jq 'map(select(.was_break == false)) | length')
echo "Completed $count pomodoros today"

Integration Examples

Git Hooks

# .git/hooks/pre-commit
#!/bin/bash
if pomodoro status --json | jq -r '.active' == "true"; then
    echo "⚠️  Pomodoro session active - consider finishing before committing"
fi

Shell Prompt

# Add to .bashrc/.zshrc
function pomodoro_prompt() {
    status=$(pomodoro status --json 2>/dev/null)
    if echo "$status" | jq -r '.active' 2>/dev/null | grep -q "true"; then
        if echo "$status" | jq -r '.status' 2>/dev/null | grep -q "paused"; then
            echo "⏸️"
        else
            echo "πŸ…"
        fi
    fi
}

# Use in prompt
PS1="$(pomodoro_prompt) $PS1"

🀝 Contributing

We welcome contributions! Please see our feature specifications for planned enhancements.

Development Setup

# Clone and setup
git clone https://github.com/ethan-k/pomodoro-cli
cd pomodoro-cli
go mod download

# Run tests
make test

# Build and test locally
make build
./bin/pomodoro --version

CI/CD Pipeline

The project uses GitHub Actions for:

  • Continuous Integration: Tests on Linux, macOS, and Windows
  • Automated Releases: Multi-platform binary builds on git tags
  • Security Scanning: Automated security analysis with Gosec
  • Code Quality: Linting with golangci-lint

Automatic Releases

Releases are automatically created when code is pushed to the main branch:

  1. Automatic Publishing: Every push to main branch triggers automatic version bumping and release creation
  2. Semantic Versioning: Version numbers are determined by commit message conventions:
    • feat: β†’ Minor version bump (e.g., 1.0.0 β†’ 1.1.0)
    • fix: β†’ Patch version bump (e.g., 1.0.0 β†’ 1.0.1)
    • feat!: or BREAKING CHANGE β†’ Major version bump (e.g., 1.0.0 β†’ 2.0.0)
  3. Multi-platform Binaries: All releases include binaries for Linux, macOS, and Windows

Manual Release (For Maintainers)

If you need to create a release manually:

# Make script executable (one-time setup)
chmod +x scripts/deploy.sh

# Create a new release (replace 1.0.0 with actual version)
./scripts/deploy.sh 1.0.0

This will:

  1. Run tests and builds
  2. Create and push a git tag
  3. Trigger GitHub Actions to build and publish release binaries

High Priority Features

  • Session templates and presets
  • Enhanced goal tracking UI
  • Comprehensive test coverage
  • Additional export formats

πŸ“„ License

MIT License - see LICENSE file for details.

πŸ™ Acknowledgments

  • Built with Cobra for CLI framework
  • UI powered by Bubble Tea
  • Cross-platform notifications via beeep
  • Data storage with SQLite

Stay focused, stay productive! πŸ…

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Packages

No packages published

Contributors 2

  •  
  •