Shellpomodoro

shellpomodoro = Shell + Pomodoro timer. Built for my own use; sharing in case it helps others too.

A cross-platform terminal-based Pomodoro timer CLI application that can be installed via pip and run anywhere. Built with Python's standard library only - no external dependencies required.

Features

• 🍅 Classic Pomodoro technique with customizable work and break durations
• ⏱️ Real-time countdown display with MM:SS format
• 🔔 Terminal bell notifications at phase transitions
• ⌨️ Keypress-controlled phase transitions (no need to wait)
• 🎨 ASCII art congratulations upon session completion
• 🖥️ Cross-platform support (Windows, macOS, Linux)
• 📦 Zero external dependencies (Python stdlib only)
• 🚀 Fast installation via pip

Installation

From PyPI (Recommended)

pip install shellpomodoro

Or using uv (even faster):

uv pip install shellpomodoro

Development Installation (from source)

git clone https://github.com/inspiringsource/shellpomodoro.git
cd shellpomodoro
#python3 -m venv .venv
python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows PowerShell
.\.venv\Scripts\Activate.ps1
# Windows CMD
.\.venv\Scripts\activate.bat
pip install -U pip
pip install -e .

Usage

Basic Usage

Start a default Pomodoro session (25min work, 5min break, 4 iterations):

shellpomodoro

Customization Options

# Custom work and break durations
shellpomodoro --work 30 --break 10

# Custom number of iterations
shellpomodoro --iterations 6

# Custom notification beeps
shellpomodoro --beeps 3

# Combine all options
shellpomodoro --work 45 --break 15 --iterations 3 --beeps 1

Command Line Options

• --work N: Set work period duration in minutes (default: 25)
• --break N: Set break period duration in minutes (default: 5)
• --iterations N: Set number of Pomodoro cycles (default: 4)
• --beeps N: Set number of notification beeps (default: 2)
• --version, -v: Show version and exit
• --help: Show help message and exit

Display modes

By default, shellpomodoro shows a countdown timer. You can pick other displays:

# default behavior (countdown)
shellpomodoro --display timer-back

# count up from 00:00
shellpomodoro --display timer-forward

# progress bar
shellpomodoro --display bar

# test-runner style dots
shellpomodoro --display dots --dot-interval 60   # one dot per minute

• --dot-interval (seconds) is optional and only used with dots. If omitted, shellpomodoro uses a sensible default (one dot per minute for long phases; ~10 dots for short ones).

Screenshots

Default Timer (timer-back)

Progress Bar

Dots Mode

How It Works

1. Work Phase: Focus on your task while the timer counts down
2. Notification: Terminal bell sounds when work phase ends
3. Keypress Transition: Press any key when ready for break
4. Break Phase: Take a break while the timer counts down
5. Repeat: Continue until all iterations are complete
6. Completion: Enjoy ASCII art congratulations!

Session Control

• Check Version: Run shellpomodoro --version or shellpomodoro -v
• Abort Session: Press Ctrl+C at any time to abort the current session
• Phase Transitions: Press Ctrl+E to end the current phase early (WORK → BREAK, BREAK → next WORK)
• Real-time Display: See countdown timer, current phase, and instructions

Detach / Reattach

• Press Ctrl+O to detach the UI; the session continues in the background.
• Run shellpomodoro attach to reattach from the same or another terminal and resume viewing.
• Hotkeys are shown once per phase on a separate line under the timer/progress line.
• Beeps continue while detached: Windows (winsound), macOS/Linux best-effort via terminal bell.

Example legend placement:

[[1/4] Focus] 24:57
Hotkeys: Ctrl+C abort • Ctrl+E end phase • Ctrl+O detach

Requirements

• Python 3.9 or higher
• No external dependencies required

Cross-Platform Compatibility

Shellpomodoro works seamlessly across different operating systems:

• Windows: Uses msvcrt for keypress detection
• Unix/Linux/macOS: Uses termios and tty for terminal control
• Terminal Bell: Uses standard \a character (may require terminal configuration)

Troubleshooting: No Beep in VS Code

If you don't hear the terminal bell when running in the VS Code integrated terminal, you may need to enable audio cues in your VS Code settings. Add the following to your settings.json:

{
  "terminal.integrated.enableVisualBell": true,
  "accessibility.signals.terminalBell": {
    "sound": "on"
  },
  "audioCues.enabled": "on",
  "audioCues.terminalBell": "on"
}

This enables the audible bell and ensures \a is played as a sound when Shellpomodoro triggers notifications.

Examples

Quick 15-minute session

shellpomodoro --work 15 --break 5 --iterations 1

Extended deep work session

shellpomodoro --work 50 --break 10 --iterations 3

Silent mode (no beeps)

shellpomodoro --beeps 0

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any issues or have questions, please open an issue on the GitHub repository.

Development History

This project was initiated using Kiro, which helped establish the initial structure and core functionality of the Pomodoro timer (the original design.md, requirements.md, and tasks.md are included in the repo). Later, the codebase was optimized and refined using Grok code to improve performance, code quality, and maintainability.