HN Explorer

Show HN: Breathe CLI – Paced resonance breathing in the macOS terminal (github.com)

132 points by marekkowalczyk ↗ HN
I built a terminal app that paces slow breathing at 6 breaths per minute for vagal tone training. It's a single Python file, stdlib only, no dependencies — just run breathe and follow the bar.

I'm a cardiology patient (HFrEF). Slow breathing at resonance frequency is one of the few non-pharmacological interventions shown to improve cardiac vagal tone and baroreflex sensitivity (Bernardi et al., Circulation 2002; Lancet 1998). I wanted a frictionless daily habit tool — no app store, no account, no subscription, just open terminal and go.

Design constraints, all grounded in the clinical literature:

- No breath retention — Valsalva risk in cardiac patients

- No rapid breathing — minimum 8-second cycles

- Exhale ≤ 2x inhale — no evidence for extreme ratios

- Immediate exit, always — q or Ctrl+C restores the terminal even on crash

The README includes a resonance frequency measurement protocol for anyone with a chest-strap HRV monitor who wants to find their individual optimum instead of using the 6 bpm default.

macOS only (uses afplay for audio cues). MIT licensed.

pip install breathe-cli

or

brew tap marekkowalczyk/breathe && brew install breathe.

38 comments

[ 4.9 ms ] story [ 73.8 ms ] thread
iammjm
Very nice. I have no heart issues but have been experimenting with extended breathing/longer exhales to calm down my sympathetic nervous system. I believe intentional breathing is a big, mostly underutilized tool all of us have to be generally more relaxed and healthier and also to calm ourselves down in stressful situations
skeledrew
Looks interesting. And it's pure Python with no 3p packages. Pretty trivial to support other OSes: make that audio player invocation configurable.
mpeg
This is cool, I have SVT and usually am able to stop an episode if I do slow breathing like that; although sometimes if that doesn’t work the modified reverse valsalva manoeuvre does it every time.
Ruslan1095
Nice work on the zero-dependency approach. I'm building a similar tool for Windows (voice-to-text) and the "no account, just run" philosophy resonates — friction kills daily habits.
mark_l_watson
I love the zero dependency implementation. I do this style of breathing during specific time periods of practicing Qi Gong. I will try your script when I get to my laptop. Thanks.
samrivera
37 days into quitting smoking and breathing exercises have been a huge help for the craving spikes. a simple terminal tool for paced breathing actually makes a lot of sense - when the craving hits at 3pm and youre staring at a screen anyway, having it right there in the terminal is way less friction than pulling out a phone app. starred.
glaslong
does it have modes for Hamon or Total Concentration breathing?
yong076
wow this repo is peaceful
ahmazroot
Not every project needs agents, workflows, and LLM integrations. Sometimes a focused tool is exactly what's needed.
thoughtpeddler
Very cool project. Is this similar to the Apple Watch ‘mindful minutes’ breathing feature? I assume it’s based on the same research as is cited in this project’s repo?
leotryhard
0 deps + afplay combo is the right move for this. Was wondering why not AVAudioPlayer until I saw the cycle lengths, overkill for 8s tempo.
marekkowalczyk
Thank you for noticing my effort. I hope the app can help you. Would you like to share your experience here?
lavaman131
This is nice. I like that it treats breathing like a small terminal ritual instead of turning it into a whole wellness app.
marekkowalczyk
Thank you for noticing. You've really captured the idea of the app.
luckykiddie
Just tries the 4-7-8 method days before. Why not support breathe holds?
marekkowalczyk
Thank you for asking. I've been building for a Market of One --- i.e. myself (heart failuer). Research shows breath holds are not recommended for my condition. Having said that, I realize this is not a universal guideline. I'm considering adding other modes besides heart failure-friendly ones. What are your use cases? Would you like to submit a feature request?
mindhash
Going to try this. I have a breathing clock gif as default page on my browser. I use it while I am passive in meetings. Resonant breathing has been great for me for IBS
marekkowalczyk
Thank you for your comment. I've never envisaged this kind of an application. Does it help you? Is there any research you can share or is it just anecdotal?
ezez2
This reminds me of this project: https://github.com/e6a5/zenta
marekkowalczyk
Thank you for bringing this to my attention. However the purpose here is medical for a Market of One (myself), not meditation. Give it a try and share your feedback.