flomo

A flowmodoro timer CLI for productivity enthusiasts

View on GitHub


Installation | Getting Started | Wiki

PyPI Version Build Status License Downloads
Issues Forks Stars

flomo is a crossplatform TUI/CLI for using the Flowtime Technique, also known as the Flowmodoro Technique. Itโ€™s a task execution helper, or in other words, a productivity booster! ๐Ÿš€

flomo allows you to work on tasks in a flow state, manage your work/break time, and track your sessions.

Built with: rich & blessed (TUI), click (CLI), notify-send for Linux notifications, playsound (Windows & Mac sound), paplay (Linux sound), sqlite3 (database).

โœจ Features

๐ŸŽ‰ Background

flomo started as a Hackathon (livestream) on June 6, 2024, with @Jonak-Adipta-Kalita and @AnubhavSC. We aimed to create a small project that was fun and could potentially help others. Weโ€™re all productivity fanatics, and this project is heavily inspired by pomo.

However, two hours in, we realized it was harder than expected. We spent a lot of time debugging and refactoring. Here are our learnings from the Hackathon.

๐ŸŒŸ Flow and Flowtime Technique

Mihaly Csikszentmihalyi was known for his work on Flow Theory. He describes โ€œflowโ€ as:

โ€œA state of being in which people become so immersed in the joy of their work or activity โ€˜that nothing else seems to matter.โ€™โ€

As developers, creators, and romantics, we often experience that state of โ€œflow.โ€ This โ€œflowโ€ can vary, sometimes increasing or decreasing.

This can be visualized with a graph:

We can take advantage of this by identifying the right time to take a breakโ€”when the โ€œflowโ€ is depleting. This is the Flowtime technique.

It works like this: If you work for x minutes, take a break for x/5 minutes. Then, repeat. โณ

This requires a good deal of discipline, meaning you need at least some natural focus. If not, check out the Pomodoro Technique! ๐Ÿ…

๐Ÿ› ๏ธ Installation

๐Ÿ“‹ Pre-requisites

๐Ÿ“ฆ Instructions

Using PyPi package

pip install flomodoro

Note: If youโ€™re on Linux, ensure /home/user/.local/bin is in your PATH. More info for Linux newbies

Installing from source

git clone https://github.com/moiSentineL/flomo.git
cd flomo
pip install -r requirements.txt

gcc -fPIC -shared -o flomo/session_id.so flomo/session_id.c

pip install -e .

๐Ÿš€ Getting Started

Initialize flomo by:

flomo init

Start a flow by:

flomo s

Start a flow with the tag work and the session name math:

flomo s -t work -n math

Check the wiki for more info ๐Ÿ“š

๐Ÿ›ค๏ธ Roadmap

Check our Kanban Board.

๐Ÿค How to Contribute

Want to help? Great! Hereโ€™s how:

  1. Fork this repo.
  2. Clone it to your local machine.
  3. Create a branch for your changes.
  4. Make your edits and test them.
  5. Commit and push your changes.
  6. Open a pull request to the main branch.

Note: if youโ€™re new to Git and Github, I suggest you read this Intro to Git and GitHub for Beginners.

Letโ€™s collaborate! ๐ŸŒŸ