https://github.com/kj-sh604/posix-pomo

POSIX-compliant shell script that implements a CLI pomodoro timer
https://github.com/kj-sh604/posix-pomo

Last synced: about 1 month ago
JSON representation

POSIX-compliant shell script that implements a CLI pomodoro timer

• Host: GitHub
• URL: https://github.com/kj-sh604/posix-pomo
• Owner: kj-sh604
• License: unlicense
• Created: 2024-02-11T11:06:14.000Z (11 months ago)
• Default Branch: master
• Last Pushed: 2024-04-06T09:05:01.000Z (9 months ago)
• Last Synced: 2024-04-06T10:21:42.193Z (9 months ago)
• Language: Shell
• Size: 216 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# `posix-pomo` - CLI Pomodoro timer 

`posix-pomo` is a simple POSIX-compliant shell script that implements a pomodoro timer for Linux and the BSDs.

![posix-pomo demo in a GIF](https://aedrielkylejavier.me/assets/posix-pomo.gif)

*GIF made with [VHS](https://github.com/charmbracelet/vhs)*

![posix-pomo notifications image 0](https://aedrielkylejavier.me/assets/posix-pomo-notif0.png)

![posix-pomo notifications image 1](https://aedrielkylejavier.me/assets/posix-pomo-notif1.png)

*example notifications using the `dunst` notification daemon on Arch Linux (btw)*

## features

- **customizable durations**: supports specifying the duration of work and break intervals in hours, minutes, or seconds.

- **cli progress bar**: displays a progress bar in the terminal showing the remaining time. *(built from scratch, no external program/library needed)*

- **notifications**: sends desktop notifications at the end of each session via `notify-send`.

- **sound alerts**: plays a sound alert at the end of each session via `mpv`.

## dependencies

- **mpv**: for playing sound alerts. *(will probably look for something more suckless in the future)*

- **notify-send**: for desktop notifications (should be preinstalled on most distros as part of `libnotify`).

- ensure you have the required sound file (`pomo-sound.mp3`) and icon file (`pomo-tomato.png`) located in the `~/.cache/pomo/` directory.

    * the repo has these files but you can also provide your own files if you'd like.

## installation

1. ensure you have all dependencies installed

2. download the `posix-pomo` script from this repository or clone the whole repo.

3. make the script executable:

   ```

   chmod +x posix-pomo

   ```

## usage

to start a timer, use the following syntax:

```

./posix-pomo  

```

- ``: either `work` for work sessions or `break` for break intervals.

- ``: the length of the timer, followed by `h` for hours, `m` for minutes, or `s` for seconds (e.g., `25m` for 25 minutes).

### examples

- start a 25-minute work session:

  ```

  ./posix-pomo work 25m

  ```

- start a 5-minute break:

  ```

  ./posix-pomo break 5m

  ```

## contributing

I honestly don't expect contributions — given how simple this is, but of course, contributions are welcome! If you have suggestions for improvements or bug fixes, please feel free to open an issue or submit a pull request.

## license

distributed under the "unlicense" license. see `LICENSE` for more information.