<p align="center">
<img src="https://raw.githubusercontent.com/moiSentineL/flomo/main/docs/assets/flomo-logo.png" width="300" style="margin-right: 10px; vertical-align: middle">
</p>
<p align="center">
<img src="https://raw.githubusercontent.com/moiSentineL/flomo/main/docs/assets/flomo-new.gif" width="400" style="margin-right: 10px; vertical-align: middle">
<img src="https://raw.githubusercontent.com/moiSentineL/flomo/main/docs/assets/flomo-track.gif" width="400" style="margin-right: 10px; vertical-align: middle">
</p>
---
<div align="center">
<a href="https://github.com/moiSentineL/flomo#-installation">Installation</a> |
<a href="https://github.com/moiSentineL/flomo#-getting-started">Getting Started</a> |
<a href="https://github.com/moiSentineL/flomo/wiki">Wiki</a>
<br>
<br>
</div>
<div align="center" styles="padding-top: 1em">
<img src="https://img.shields.io/pypi/v/flomodoro?style=flat-square" alt="PyPI Version">
<img src="https://github.com/moiSentineL/flomo/actions/workflows/publish.yml/badge.svg?style=plastic" alt="Build Status">
<img src="https://img.shields.io/github/license/moiSentineL/flomo?style=flat-square" alt="License">
<img src="https://img.shields.io/pypi/dm/flomodoro?style=flat-square" alt="Downloads">
<br>
<img src="https://img.shields.io/github/issues/moiSentineL/flomo?style=flat-square" alt="Issues">
<img src="https://img.shields.io/github/forks/moiSentineL/flomo?style=flat-square" alt="Forks">
<img src="https://img.shields.io/github/stars/moiSentineL/flomo?style=flat-square" alt="Stars">
</div>
---
`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](https://github.com/Textualize/rich) & [blessed](https://github.com/jquast/blessed) (TUI), [click](https://click.palletsprojects.com/en/8.1.x/) (CLI), [notify-send](https://man.archlinux.org/man/notify-send.1) for Linux notifications, [playsound](https://github.com/TaylorSMarks/playsound) (Windows & Mac sound), [paplay](https://linux.die.net/man/1/paplay) (Linux sound), [sqlite3](https://www.sqlite.org) (database).
## ✨ Features
- **Cross-Platform** 🌐
- Stopwatch for Flow and Timer for Breaks ⏱️
- Session tracker (date, duration, tag, and session) 🗓️
- Session manager: easily manipulate the sessions via CLI ⚙️
- Customizable, Clean UI 🎨
- Notifications (Linux only, for now) 🔔
- Fairly easy-to-use, I suppose 🤔
- (Potential) productivity booster 💥
## 🎉 Background
`flomo` started as a Hackathon ([livestream](https://www.youtube.com/live/xyqQgPEozv0)) on June 6, 2024, with [@Jonak-Adipta-Kalita](https://github.com/Jonak-Adipta-Kalita) and [@AnubhavSC](https://github.com/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](https://github.com/kevinschoon/pomo).
However, two hours in, we realized it was harder than expected. We spent a lot of time debugging and refactoring. [Here](https://nibirsan.org/blog/p/the-hackathon-experience/) are our learnings from the Hackathon.
## 🌟 Flow and Flowtime Technique
[Mihaly Csikszentmihalyi](https://en.wikipedia.org/wiki/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:
<p align="center">
<img src="https://raw.githubusercontent.com/moiSentineL/flomo/main/docs/assets/flow-graph.png" width="400">
</p>
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](https://www.pomodorotechnique.com/)! 🍅
## 🛠️ Installation
### 📋 Pre-requisites
- 🐍 [Python](https://www.python.org/) ≥ 3.12
- 📦 [pip](https://pip.pypa.io/en/stable/installation/)
- 🛠️ [GCC Compiler](https://gcc.gnu.org/) **if** installing from source.
### 📦 Instructions
#### Using PyPi package
```bash
pip install flomodoro
```
_Note: If you're on Linux, ensure `/home/user/.local/bin` is in your `PATH`. [More info for Linux newbies](https://linuxize.com/post/how-to-add-directory-to-path-in-linux/)_
#### Installing from source
```bash
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:
```bash
flomo init
```
Start a flow by:
```bash
flomo s
```
Start a flow with the tag `work` and the session name `math`:
```bash
flomo s -t work -n math
```
### Check the [wiki](https://github.com/moiSentineL/flomo/wiki) for more info 📚
## 🛤️ Roadmap
- ✅ Add sound on timer/stopwatch start
- ✅ Notification (only Linux for now)
- ✅ Configure colors
- ✅ Track sessions
- ✅ Configure colors
- 🟧 Skipping Break
- 🟧 Chart Generation / Statistics
Check our [Kanban Board](https://github.com/users/moiSentineL/projects/2).
## 🤝 How to Contribute
Want to help? Great! Here's how:
1. **Fork** this [repo](https://github.com/moiSentineL/flomo/fork).
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](https://github.com/moiSentineL/flomo/pulls)** 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](https://product.hubspot.com/blog/git-and-github-tutorial-for-beginners)._
Let's collaborate! 🌟
[^1]: Csikszentmihalyi, M. (1990). _Flow: The Psychology of Optimal Experience_. New York: Harper and Row. p. 15 [ISBN](<https://en.wikipedia.org/wiki/ISBN_(identifier)>) [0-06-092043-2](https://en.wikipedia.org/wiki/Special:BookSources/0-06-092043-2).
Raw data
{
"_id": null,
"home_page": "https://github.com/moiSentineL/flomo",
"name": "flomodoro",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "cli, productivity, cli-application",
"author": "Dark Circles",
"author_email": "<nibir@nibirsan.org>, <jonakadiptakalita@gmail.com>, <anubhavnath60@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/5a/b8/84aa6b1987a56544ea3ff6909235bb2ae5ceabbeaf9a0d99ef120ce2faf7/flomodoro-1.1.0.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/moiSentineL/flomo/main/docs/assets/flomo-logo.png\" width=\"300\" style=\"margin-right: 10px; vertical-align: middle\">\n</p>\n<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/moiSentineL/flomo/main/docs/assets/flomo-new.gif\" width=\"400\" style=\"margin-right: 10px; vertical-align: middle\">\n <img src=\"https://raw.githubusercontent.com/moiSentineL/flomo/main/docs/assets/flomo-track.gif\" width=\"400\" style=\"margin-right: 10px; vertical-align: middle\">\n</p>\n\n---\n\n<div align=\"center\">\n <a href=\"https://github.com/moiSentineL/flomo#-installation\">Installation</a> | \n <a href=\"https://github.com/moiSentineL/flomo#-getting-started\">Getting Started</a> | \n <a href=\"https://github.com/moiSentineL/flomo/wiki\">Wiki</a>\n <br>\n <br>\n</div>\n\n<div align=\"center\" styles=\"padding-top: 1em\">\n\t <img src=\"https://img.shields.io/pypi/v/flomodoro?style=flat-square\" alt=\"PyPI Version\">\n <img src=\"https://github.com/moiSentineL/flomo/actions/workflows/publish.yml/badge.svg?style=plastic\" alt=\"Build Status\">\n <img src=\"https://img.shields.io/github/license/moiSentineL/flomo?style=flat-square\" alt=\"License\">\n <img src=\"https://img.shields.io/pypi/dm/flomodoro?style=flat-square\" alt=\"Downloads\">\n <br>\n <img src=\"https://img.shields.io/github/issues/moiSentineL/flomo?style=flat-square\" alt=\"Issues\">\n <img src=\"https://img.shields.io/github/forks/moiSentineL/flomo?style=flat-square\" alt=\"Forks\">\n <img src=\"https://img.shields.io/github/stars/moiSentineL/flomo?style=flat-square\" alt=\"Stars\">\n</div>\n\n---\n\t\n`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! \ud83d\ude80\n\n`flomo` allows you to work on tasks in a flow state, manage your work/break time, and track your sessions.\n\nBuilt with: [rich](https://github.com/Textualize/rich) & [blessed](https://github.com/jquast/blessed) (TUI), [click](https://click.palletsprojects.com/en/8.1.x/) (CLI), [notify-send](https://man.archlinux.org/man/notify-send.1) for Linux notifications, [playsound](https://github.com/TaylorSMarks/playsound) (Windows & Mac sound), [paplay](https://linux.die.net/man/1/paplay) (Linux sound), [sqlite3](https://www.sqlite.org) (database).\n\n## \u2728 Features\n\n- **Cross-Platform** \ud83c\udf10\n- Stopwatch for Flow and Timer for Breaks \u23f1\ufe0f \n- Session tracker (date, duration, tag, and session) \ud83d\uddd3\ufe0f\n- Session manager: easily manipulate the sessions via CLI \u2699\ufe0f\n- Customizable, Clean UI \ud83c\udfa8\n- Notifications (Linux only, for now) \ud83d\udd14\n- Fairly easy-to-use, I suppose \ud83e\udd14\n- (Potential) productivity booster \ud83d\udca5\n\n## \ud83c\udf89 Background\n\n`flomo` started as a Hackathon ([livestream](https://www.youtube.com/live/xyqQgPEozv0)) on June 6, 2024, with [@Jonak-Adipta-Kalita](https://github.com/Jonak-Adipta-Kalita) and [@AnubhavSC](https://github.com/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](https://github.com/kevinschoon/pomo).\n\nHowever, two hours in, we realized it was harder than expected. We spent a lot of time debugging and refactoring. [Here](https://nibirsan.org/blog/p/the-hackathon-experience/) are our learnings from the Hackathon.\n\n## \ud83c\udf1f Flow and Flowtime Technique\n\n[Mihaly Csikszentmihalyi](https://en.wikipedia.org/wiki/Mihaly_Csikszentmihalyi) was known for his work on **Flow Theory**. He describes \"flow\" as:\n\n> \"A state of being in which people become so immersed in the joy of their work or activity 'that nothing else seems to matter.'\"\n\nAs developers, creators, and romantics, we often experience that state of \"flow.\" This \"flow\" can **vary**, sometimes increasing or decreasing.\n\nThis can be visualized with a graph:\n\n<p align=\"center\">\n<img src=\"https://raw.githubusercontent.com/moiSentineL/flomo/main/docs/assets/flow-graph.png\" width=\"400\">\n</p>\n\nWe can take advantage of this by identifying the **right time** to take a break\u2014when the \"flow\" is depleting. This is the Flowtime technique.\n\nIt works like this: **If you work for x minutes, take a break for x/5 minutes. Then, repeat.** \u23f3\n\nThis requires a good deal of discipline, meaning you need at least some natural focus. If not, check out the [Pomodoro Technique](https://www.pomodorotechnique.com/)! \ud83c\udf45\n\n## \ud83d\udee0\ufe0f Installation\n\n### \ud83d\udccb Pre-requisites\n\n- \ud83d\udc0d [Python](https://www.python.org/) \u2265 3.12\n- \ud83d\udce6 [pip](https://pip.pypa.io/en/stable/installation/)\n- \ud83d\udee0\ufe0f [GCC Compiler](https://gcc.gnu.org/) **if** installing from source.\n\n### \ud83d\udce6 Instructions\n\n#### Using PyPi package\n\n```bash\npip install flomodoro\n```\n\n_Note: If you're on Linux, ensure `/home/user/.local/bin` is in your `PATH`. [More info for Linux newbies](https://linuxize.com/post/how-to-add-directory-to-path-in-linux/)_\n\n#### Installing from source\n\n```bash\ngit clone https://github.com/moiSentineL/flomo.git\ncd flomo\npip install -r requirements.txt\n\ngcc -fPIC -shared -o flomo/session_id.so flomo/session_id.c\n\npip install -e .\n```\n\n## \ud83d\ude80 Getting Started\n\nInitialize flomo by:\n\n```bash\nflomo init\n```\n\nStart a flow by:\n\n```bash\nflomo s\n```\n\nStart a flow with the tag `work` and the session name `math`:\n\n```bash\nflomo s -t work -n math\n```\n\n### Check the [wiki](https://github.com/moiSentineL/flomo/wiki) for more info \ud83d\udcda\n\n## \ud83d\udee4\ufe0f Roadmap\n\n- \u2705 Add sound on timer/stopwatch start\n- \u2705 Notification (only Linux for now)\n- \u2705 Configure colors\n- \u2705 Track sessions\n- \u2705 Configure colors\n- \ud83d\udfe7 Skipping Break\n- \ud83d\udfe7 Chart Generation / Statistics\n\nCheck our [Kanban Board](https://github.com/users/moiSentineL/projects/2).\n\n## \ud83e\udd1d How to Contribute\n\nWant to help? Great! Here's how:\n\n1. **Fork** this [repo](https://github.com/moiSentineL/flomo/fork).\n2. **Clone** it to your local machine.\n3. **Create a branch** for your changes.\n4. **Make your edits** and test them.\n5. **Commit and push** your changes.\n6. **[Open a pull request](https://github.com/moiSentineL/flomo/pulls)** to the `main` branch.\n\n_Note: if you're new to Git and Github, I suggest you read this [Intro to Git and GitHub for Beginners](https://product.hubspot.com/blog/git-and-github-tutorial-for-beginners)._\n\nLet's collaborate! \ud83c\udf1f\n\n[^1]: Csikszentmihalyi, M. (1990). _Flow: The Psychology of Optimal Experience_. New York: Harper and Row. p. 15 [ISBN](<https://en.wikipedia.org/wiki/ISBN_(identifier)>) [0-06-092043-2](https://en.wikipedia.org/wiki/Special:BookSources/0-06-092043-2).\n",
"bugtrack_url": null,
"license": null,
"summary": "A Flowmodoro Timer CLI for producitivity enthusiasts.",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/moiSentineL/flomo"
},
"split_keywords": [
"cli",
" productivity",
" cli-application"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0ecc696b03fd0a1e951329471f732b0031096bca6e58d665901db98b7f8b7608",
"md5": "1b8a2a6458594473f99edafe071d7dc8",
"sha256": "65a94be1dcd81c6f42d6707423f14bcd73cff77f16b03108785d748ecaf77b02"
},
"downloads": -1,
"filename": "flomodoro-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1b8a2a6458594473f99edafe071d7dc8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 57679,
"upload_time": "2024-09-05T14:40:26",
"upload_time_iso_8601": "2024-09-05T14:40:26.408348Z",
"url": "https://files.pythonhosted.org/packages/0e/cc/696b03fd0a1e951329471f732b0031096bca6e58d665901db98b7f8b7608/flomodoro-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5ab884aa6b1987a56544ea3ff6909235bb2ae5ceabbeaf9a0d99ef120ce2faf7",
"md5": "10ba60da706ed095f58d4f5143c03b25",
"sha256": "fbc6da4ee08c406cbfa4bb6af27c36edd86d2cbae023547dce38460047e0d953"
},
"downloads": -1,
"filename": "flomodoro-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "10ba60da706ed095f58d4f5143c03b25",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 60813,
"upload_time": "2024-09-05T14:40:27",
"upload_time_iso_8601": "2024-09-05T14:40:27.598037Z",
"url": "https://files.pythonhosted.org/packages/5a/b8/84aa6b1987a56544ea3ff6909235bb2ae5ceabbeaf9a0d99ef120ce2faf7/flomodoro-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-05 14:40:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "moiSentineL",
"github_project": "flomo",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "flomodoro"
}
JSON
