🌀 flow

A mouse-first terminal focus app. Pomodoro timer · nested to-dos · daily habit tracker · ambient/lofi audio mixer · app blocker — all on one screen, in one file, with zero Python dependencies.

flow.demo.mp4

_{▶ Full demo, with sound. If the player doesn't load, watch it on the Releases page · screenshot}

---

Why flow?

Most focus tools scatter your attention across a timer app, a to-do app, a habit tracker, a music tab and a website blocker. flow folds all of that into a single calm terminal screen you can drive entirely with the mouse — or never leave the home row. No accounts, no telemetry, no cloud. Your data is just three JSON files under ~/.config/flow/.

• One file, zero Python dependencies. The whole app is one ~2,800-line script — pure standard library + curses.
• Mouse-first, keyboard-fast. Click anything, or learn the shortcuts shown right on each tab.
• Yours, offline, forever. All state lives in plain JSON under ~/.config/flow/.

---

Features

⏱️ Pomodoro timer	Work / break cycles, auto-start, session targets and a named countdown to your big day.
✅ Nested to-dos	Unlimited subtasks, collapse/expand, progress counts — a real outline, not a flat list.
🔥 Habit tracker	Daily habits with streaks and a 7-day ●/○ grid.
🎧 Ambient audio mixer	Layer multiple sounds at once — rain, café, brown noise, lofi and more — each mixed live.
📊 Stats	Daily / Habits / Month / Year views with goal-based progress rings, plus CSV + JSON export.
🚫 App blocker	Fuzzy-search installed apps and have flow kill distractions while you focus.
🌈 Live visualizer	A real audio-reactive spectrum strip (via cava) along the bottom.

---

Install

Note

flow runs on Linux and macOS. It needs nothing beyond Python 3.8+ — optional system tools (below) unlock audio, the visualizer and native dialogs.

pipx — recommended

pipx installs flow into its own isolated environment and puts the flow command on your PATH. It's the cleanest way to install a CLI app and it works everywhere — including Arch / Omarchy, where a plain pip install is blocked (see the note below).

pipx install flow-focus
flow

_{Don't have pipx? Install it once: sudo pacman -S python-pipx (Arch/Omarchy) · brew install pipx (macOS) · python3 -m pip install --user pipx (others).}

pip

pip install flow-focus
flow

Note

On Arch, Omarchy, Debian, Ubuntu and other distros with an externally-managed Python, a bare pip install is refused on purpose (PEP 668). Use pipx (above), or install into a virtual environment:

python3 -m venv .venv && source .venv/bin/activate
pip install flow-focus

_{Want the absolute latest, straight from main? pipx install git+https://github.com/thepathless/flow.git}

From source

git clone https://github.com/thepathless/flow.git
cd flow
./flow                 # run directly — no install step needed
./install.sh           # or copy the script to ~/.local/bin

Windows: not supported yet — ambient audio and the app blocker rely on Linux/macOS facilities. Use WSL in the meantime.

---

Optional system tools

flow works with nothing else installed, but these unlock extra features — it detects them at runtime and degrades gracefully:

Tool	Enables
mpv	ambient / lofi audio playback
paplay	transition chimes (else terminal bell)
cava	real audio-reactive spectrum visualizer
zenity / kdialog	native folder picker for stats export
fzf	terminal fuzzy folder picker for stats export

---

Keyboard cheatsheet

Every view's shortcut is the highlighted letter on its tab, so you can learn navigation at a glance — but here's the full set:

Key	Action		Key	Action
Tab	switch panel		space	start / pause timer
h	home		m	mute
f	focus		+ / -	volume
o	sounds		v	toggle visualizer
t	stats		?	help
s	settings		q	quit

---

Repository layout

flow                 the application — a single script, the source of truth
install.sh           installs the flow script to ~/.local/bin from a checkout
pyproject.toml       pip / packaging metadata
setup.py             installs the `flow` script via pip
packaging/           AUR PKGBUILD + Homebrew formula for maintainers
assets/              poster image used in this README
tools/               byte-compile + render smoke tests
.github/workflows/   CI (byte-compile + package build check)

---

Contributing

The entire app is the single flow script, so contributing is refreshingly simple: edit flow, then run it in a real terminal and exercise the view you changed — curses UIs can't be meaningfully checked by reading output alone. The smoke tests in tools/ byte-compile and render-check the script; CI runs the same on every push. Issues and pull requests are welcome.

---

License

MIT. Bundled ambient recordings are CC0 / public-domain.

---

_{For my Mimi — my favorite reason to look up from the screen. 💗}