| Name | shellpomodoro JSON |
| Version |
0.1.5
JSON |
| download |
| home_page | None |
| Summary | A cross-platform terminal Pomodoro timer (stdlib-only) with keypress pauses and an ASCII reward banner. |
| upload_time | 2025-09-07 12:35:47 |
| maintainer | None |
| docs_url | None |
| author | Avi |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
pomodoro
cli
timer
productivity
terminal
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Shellpomodoro
---
[](https://pypi.org/project/shellpomodoro/) [](https://pypi.org/project/shellpomodoro/) [](https://opensource.org/licenses/MIT)
`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)
```bash
pip install shellpomodoro
```
Or using `uv` (even faster):
```bash
uv pip install shellpomodoro
````
### Development Installation (from source)
```bash
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):
```bash
shellpomodoro
```
### Customization Options
```bash
# 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:
```bash
# 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:
```bash
[[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`:
```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
```bash
shellpomodoro --work 15 --break 5 --iterations 1
```
### Extended deep work session
```bash
shellpomodoro --work 50 --break 10 --iterations 3
```
### Silent mode (no beeps)
```bash
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.
Raw data
{
"_id": null,
"home_page": null,
"name": "shellpomodoro",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "pomodoro, cli, timer, productivity, terminal",
"author": "Avi",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/0a/9d/468226b4b2994cec65e1e5afe2d099af7f05997e2f67d6f3ed58255f5c36/shellpomodoro-0.1.5.tar.gz",
"platform": null,
"description": "# Shellpomodoro\n\n---\n\n[](https://pypi.org/project/shellpomodoro/) [](https://pypi.org/project/shellpomodoro/) [](https://opensource.org/licenses/MIT)\n\n`shellpomodoro` = Shell + Pomodoro timer. Built for my own use; sharing in case it helps others too.\n\nA 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.\n\n## Features\n\n- \ud83c\udf45 Classic Pomodoro technique with customizable work and break durations\n- \u23f1\ufe0f Real-time countdown display with MM:SS format\n- \ud83d\udd14 Terminal bell notifications at phase transitions\n- \u2328\ufe0f Keypress-controlled phase transitions (no need to wait)\n- \ud83c\udfa8 ASCII art congratulations upon session completion\n- \ud83d\udda5\ufe0f Cross-platform support (Windows, macOS, Linux)\n- \ud83d\udce6 Zero external dependencies (Python stdlib only)\n- \ud83d\ude80 Fast installation via pip\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install shellpomodoro\n```\n\nOr using `uv` (even faster):\n\n```bash\nuv pip install shellpomodoro\n````\n\n### Development Installation (from source)\n\n```bash\ngit clone https://github.com/inspiringsource/shellpomodoro.git\ncd shellpomodoro\n#python3 -m venv .venv\npython -m venv .venv\n# macOS/Linux\nsource .venv/bin/activate\n# Windows PowerShell\n.\\.venv\\Scripts\\Activate.ps1\n# Windows CMD\n.\\.venv\\Scripts\\activate.bat\npip install -U pip\npip install -e .\n```\n\n## Usage\n\n### Basic Usage\n\nStart a default Pomodoro session (25min work, 5min break, 4 iterations):\n\n```bash\nshellpomodoro\n```\n\n### Customization Options\n\n```bash\n# Custom work and break durations\nshellpomodoro --work 30 --break 10\n\n# Custom number of iterations\nshellpomodoro --iterations 6\n\n# Custom notification beeps\nshellpomodoro --beeps 3\n\n# Combine all options\nshellpomodoro --work 45 --break 15 --iterations 3 --beeps 1\n```\n\n### Command Line Options\n\n- `--work N`: Set work period duration in minutes (default: 25)\n- `--break N`: Set break period duration in minutes (default: 5)\n- `--iterations N`: Set number of Pomodoro cycles (default: 4)\n- `--beeps N`: Set number of notification beeps (default: 2)\n- `--version`, `-v`: Show version and exit\n- `--help`: Show help message and exit\n\n### Display modes\n\nBy default, shellpomodoro shows a countdown timer. You can pick other displays:\n\n```bash\n# default behavior (countdown)\nshellpomodoro --display timer-back\n\n# count up from 00:00\nshellpomodoro --display timer-forward\n\n# progress bar\nshellpomodoro --display bar\n\n# test-runner style dots\nshellpomodoro --display dots --dot-interval 60 # one dot per minute\n```\n\n- `--dot-interval` (seconds) is optional and only used with dots.\n If omitted, shellpomodoro uses a sensible default (one dot per minute for long phases; ~10 dots for short ones).\n\n### Screenshots\n\n**Default Timer (timer-back)**\n\n\n**Progress Bar**\n\n\n**Dots Mode**\n\n\n## How It Works\n\n1. **Work Phase**: Focus on your task while the timer counts down\n2. **Notification**: Terminal bell sounds when work phase ends\n3. **Keypress Transition**: Press any key when ready for break\n4. **Break Phase**: Take a break while the timer counts down\n5. **Repeat**: Continue until all iterations are complete\n6. **Completion**: Enjoy ASCII art congratulations!\n\n### Session Control\n\n- **Check Version**: Run `shellpomodoro --version` or `shellpomodoro -v`\n- **Abort Session**: Press `Ctrl+C` at any time to abort the current session\n- **Phase Transitions**: Press `Ctrl+E` to end the current phase early (WORK \u2192 BREAK, BREAK \u2192 next WORK)\n- **Real-time Display**: See countdown timer, current phase, and instructions\n\n## Detach / Reattach\n\n- Press `Ctrl+O` to **detach** the UI; the session continues in the background.\n- Run `shellpomodoro attach` to **reattach** from the same or another terminal and resume viewing.\n- Hotkeys are shown once per phase on a separate line under the timer/progress line.\n- Beeps continue while detached: Windows (winsound), macOS/Linux best-effort via terminal bell.\n\nExample legend placement:\n\n```bash\n[[1/4] Focus] 24:57\nHotkeys: Ctrl+C abort \u2022 Ctrl+E end phase \u2022 Ctrl+O detach\n```\n\n## Requirements\n\n- Python 3.9 or higher\n- No external dependencies required\n\n## Cross-Platform Compatibility\n\nShellpomodoro works seamlessly across different operating systems:\n\n- **Windows**: Uses `msvcrt` for keypress detection\n- **Unix/Linux/macOS**: Uses `termios` and `tty` for terminal control\n- **Terminal Bell**: Uses standard `\\a` character (may require terminal configuration)\n\n### Troubleshooting: No Beep in VS Code\n\nIf 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`:\n\n```json\n{\n \"terminal.integrated.enableVisualBell\": true,\n \"accessibility.signals.terminalBell\": {\n \"sound\": \"on\"\n },\n \"audioCues.enabled\": \"on\",\n \"audioCues.terminalBell\": \"on\"\n}\n```\n\nThis enables the audible bell and ensures `\\a` is played as a sound when Shellpomodoro triggers notifications.\n\n## Examples\n\n### Quick 15-minute session\n\n```bash\nshellpomodoro --work 15 --break 5 --iterations 1\n```\n\n### Extended deep work session\n\n```bash\nshellpomodoro --work 50 --break 10 --iterations 3\n```\n\n### Silent mode (no beeps)\n\n```bash\nshellpomodoro --beeps 0\n```\n\n## License\n\nMIT License\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Support\n\nIf you encounter any issues or have questions, please open an issue on the GitHub repository.\n\n## Development History\n\nThis 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.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A cross-platform terminal Pomodoro timer (stdlib-only) with keypress pauses and an ASCII reward banner.",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://github.com/inspiringsource/shellpomodoro",
"Issues": "https://github.com/inspiringsource/shellpomodoro/issues",
"Repository": "https://github.com/inspiringsource/shellpomodoro"
},
"split_keywords": [
"pomodoro",
" cli",
" timer",
" productivity",
" terminal"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e7dc03329e9ea2af0433dcf64d9c5fffd03b7ea7b1d953a49114f53470487002",
"md5": "525684dbab1f13aa139c0852097dffd2",
"sha256": "759a58989c595e3e2a4f9401972d5f3a0e41f963d2b0a5e35efe5030ec59ce9a"
},
"downloads": -1,
"filename": "shellpomodoro-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "525684dbab1f13aa139c0852097dffd2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 24136,
"upload_time": "2025-09-07T12:35:46",
"upload_time_iso_8601": "2025-09-07T12:35:46.099404Z",
"url": "https://files.pythonhosted.org/packages/e7/dc/03329e9ea2af0433dcf64d9c5fffd03b7ea7b1d953a49114f53470487002/shellpomodoro-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0a9d468226b4b2994cec65e1e5afe2d099af7f05997e2f67d6f3ed58255f5c36",
"md5": "895105cbe342af445586726f57e73f22",
"sha256": "77ac1c2b77ab1338324bafd16fe6dcafce6b2ed9f899a2dd309bd78d369a057e"
},
"downloads": -1,
"filename": "shellpomodoro-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "895105cbe342af445586726f57e73f22",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 25651,
"upload_time": "2025-09-07T12:35:47",
"upload_time_iso_8601": "2025-09-07T12:35:47.733575Z",
"url": "https://files.pythonhosted.org/packages/0a/9d/468226b4b2994cec65e1e5afe2d099af7f05997e2f67d6f3ed58255f5c36/shellpomodoro-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-07 12:35:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "inspiringsource",
"github_project": "shellpomodoro",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "shellpomodoro"
}
