Flowmodoro CLI
Flowmodoro is a minimalist command-line productivity tool based on the flowmodoro technique -- a flexible alternative to the traditional Pomodoro method.
This tool helps you manage your work and break cycles dynamically, calculating personalized break times based on how long you've been working.
Features
- Start and track focused work sessions
- Automatically calculate break durations (20% of time worked)
- Check your current session status anytime
- Session persistence across terminal sessions
- Minimal, fast, and dependency-free
Installation
1. Clone and install manually
git clone https://github.com/LuisFerRodVar/flowmodoro-cli.git
cd flowmodoro-cli
chmod +x flowmodoro.py
sudo mv flowmodoro.py /usr/local/bin/flowmodoro
cd flowmodoro-cli
chmod +x flowmodoro.py
sudo mv flowmodoro.py /usr/local/bin/flowmodoro
Now you can use it as a global command:
flowmodoro start
Usage
Start a work session
flowmodoro start
Take a break (after working)
flowmodoro break
Break time will be calculated as 20% of the time worked (minimum 1 minute).
Check session status
flowmodoro status
Outputs:
- Current mode:
workorbreak - Time worked or remaining break time in seconds and HH:MM:SS format
How it works
- Stores session state in
/tmp/flowmodoro_state.json - Uses
time.time()to calculate elapsed time - Keeps no history -- designed to be simple and ephemeral
Example
$ flowmodoro start
Work session started.
# ... after a while
$ flowmodoro break
Work session ended. Duration: 42 minutes
Starting break for 8 minutes.
$ flowmodoro status
mode=break
remaining_seconds=392
remaining_hms=00:06:32
Work session started.
# ... after a while
$ flowmodoro break
Work session ended. Duration: 42 minutes
Starting break for 8 minutes.
$ flowmodoro status
mode=break
remaining_seconds=392
remaining_hms=00:06:32
License
MIT License (c) 2025 Luis RodVar