A minimalist macOS CLI Pomodoro timer built in Go with advanced features for productivity tracking.
- 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 Alerts π - Sound notifications when sessions complete (configurable)
- Desktop Notifications - Native OS notifications with session details
- Silent Mode - Disable audio for individual sessions with
--silentflag
- 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
- 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
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 github.com/ethan-k/pomodoro-cli@latestgit clone https://github.com/ethan-k/pomodoro-cli
cd pomodoro-cli
make build
make installpomodoro --version# 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| 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 |
| Command | Description | Examples |
|---|---|---|
history |
View session history | pomodoro history --today |
config |
Manage configuration | pomodoro config show |
| 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 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"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)
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"# Set volume in config file
pomodoro config audio --volume 0.8# 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.jsonEach 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
# 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)# 50-minute deep work session
pomodoro start "Complex analysis" --duration 50m --tags analysis,research
# Custom break
pomodoro break 15m --wait# Silent mode for meetings
pomodoro start "Team meeting" --duration 1h --silent --tags meetingmake 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/binpomodoro-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
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"# .git/hooks/pre-commit
#!/bin/bash
if pomodoro status --json | jq -r '.active' == "true"; then
echo "β οΈ Pomodoro session active - consider finishing before committing"
fi# 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"We welcome contributions! Please see our feature specifications for planned enhancements.
# 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 --versionThe 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
Releases are automatically created when code is pushed to the main branch:
- Automatic Publishing: Every push to main branch triggers automatic version bumping and release creation
- 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!:orBREAKING CHANGEβ Major version bump (e.g., 1.0.0 β 2.0.0)
- Multi-platform Binaries: All releases include binaries for Linux, macOS, and Windows
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.0This will:
- Run tests and builds
- Create and push a git tag
- Trigger GitHub Actions to build and publish release binaries
- Session templates and presets
- Enhanced goal tracking UI
- Comprehensive test coverage
- Additional export formats
MIT License - see LICENSE file for details.
- Built with Cobra for CLI framework
- UI powered by Bubble Tea
- Cross-platform notifications via beeep
- Data storage with SQLite
Stay focused, stay productive! π