breathe-cli at a glance
As of 2026-05-31
breathe-cli: clinical breathing practice in 84 lines of Python
breathe-cli (MIT, v1.8, Python stdlib-only, macOS-only) is a 24-hour-old terminal paced breathing tool by cardiology patient Marek Kowalczyk. It targets 6 breaths/minute — the resonance frequency backed by two peer-reviewed papers in The Lancet and Circulation — with three time-of-day presets, a clinical safety system, and zero external dependencies. It hit HN Show HN with 90 points; the thread's dominant reaction was relief at a focused, zero-account tool in a sea of AI-bloated software.
You're staring at a screen at 3pm, cortisol doing whatever cortisol does, and you know a five-minute breathing session would fix the edge off. But you're already in the terminal. Opening an app, finding the right preset, doing the login — the friction is enough to skip the whole thing. You stay on edge, keep typing.
breathe-cli is a 2026-05-30 release that assumes you never leave the terminal in the first place. 1 It landed on Hacker News yesterday as a Show HN with 90 points and 13 comments — modest by headline-grabbing standards, but notably uniform in tone: people found it immediately usable and refreshingly not over-engineered. 2One comment from ahmazroot captured the dominant sentiment: "Not every project needs agents, workflows, and LLM integrations. Sometimes a focused tool is exactly what's needed." 2
正在加载内容卡片…
What it is
breathe-cli (authored by Marek Kowalczyk, MIT license, v1.8 "Science & Safety") is a single-file Python script — 84.8% of the repo is Python, the rest is documentation HTML — that runs a paced resonance breathing exercise in your terminal. 1 Zero external dependencies. No curses library, no third-party packages: pure stdlib plus ANSI escape codes drawn directly. Python 3.7 or newer is all it needs. 3
The tool targets 6 breaths per minute, the population-level default for resonance breathing. An expanding/contracting bar fills the screen with each inhale and exhale, with a soft audio cue from
/usr/bin/afplay — which is why this is macOS-only. Linux and Windows users are out until someone makes the audio backend configurable, something HN commenter skeledrew noted takes "pretty trivial" effort. 2Sessions are logged automatically to
~/.breathe_log.csv: date, preset, ratio, target duration, actual duration, breath count, completion percentage, and status. That's it. No cloud sync, no streak gamification.正在加载统计卡片…
The clinical basis
The author, Kowalczyk, is a heart failure (HFrEF) patient. That context explains why breathe-cli's design constraints are unusually precise — they're not UX defaults, they're grounded in the clinical literature he consulted for his own condition.
In the Show HN post, Kowalczyk wrote: "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." 2
The two load-bearing papers are real and peer-reviewed. Bernardi et al. (1998) in The Lancet (PMID: 9643792) ran a randomized controlled trial on 50 CHF patients and found that slow breathing at 6 breaths/minute improved resting oxygen saturation, exercise tolerance, and dyspnea scores. 4 Bernardi et al. (2002) in Circulation (PMID: 11790690) followed with 81 CHF patients across NYHA classes I–IV: slow breathing at 6 bpm significantly increased baroreflex sensitivity (5.0 ± 0.3 ms/mm Hg at rest vs. 6.1 ± 0.5 ms/mm Hg during slow breathing) while also lowering blood pressure. 5 These findings are what drove the 6 bpm default, not convention.
The README is careful about scope. As Kowalczyk put it: "This app is a habit tool that makes daily practice frictionless: open terminal, run breathe, follow the bar. It is not a medical device." 1
How it works
breathe-cli ships three time-of-day presets that activate automatically:
| Time window | Preset | Duration | Ratio (inhale:exhale) |
|---|---|---|---|
| Morning | balanced | 10 min | 5 s : 5 s |
| Midday | extended | 20 min | 4 s : 6 s |
| Evening | calm | 15 min | 4 s : 6 s |
All three target exactly 6 breaths per minute. 1 The longer exhale in the midday and evening presets is deliberate — a prolonged exhale extends the parasympathetic phase of each breath cycle, biasing the autonomic nervous system toward calm rather than alert.
The safety system is the part that shows clinical thinking. breathe-cli refuses breath holds (Valsalva maneuver risk), enforces a minimum 8-second full cycle (no hyperventilation), caps exhale at 2× inhale, and exits cleanly on
q or Ctrl+C with the terminal fully restored. 1 The 4-7-8 pattern popular in wellness apps is explicitly rejected — the 7-second hold is considered unsafe for certain cardiac profiles. The codebase has 25 manual acceptance tests covering TUI behavior and automated tests for arithmetic, safety rejections, and preset invariants.Install
# Option 1: pip (PyPI wheel, 15 KB)
pip install breathe-cli
# Option 2: Homebrew tap
brew tap marekkowalczyk/breathe && brew install breatheThen:
breathe # auto-selects the time-of-day preset
breathe balanced # force a specific presetThe PyPI wheel is 15 KB. The project was created May 30, has 49 commits, and was last pushed May 31 at 16:57 UTC — so this is genuinely a 24-hour-old tool reaching you at near-inception velocity. 1 6
What the community found
The HN thread didn't have any real criticism of the tool itself — just the macOS constraint. A few observations worth noting:
HN user mpeg, who has SVT (supraventricular tachycardia), wrote: "I have SVT and usually am able to stop an episode if I do slow breathing like that." 2 This isn't a clinical endorsement, but it's the kind of real-world signal that separates tools built from personal need from those built speculatively.
samrivera put the terminal-native angle plainly: "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 you're staring at a screen anyway, having it right there in the terminal is way less friction than pulling out a phone app." 2
Ruslan1095 named the design philosophy directly: "the 'no account, just run' philosophy resonates — friction kills daily habits." 2
正在加载内容卡片…
Caveats
- macOS only, hard dependency. The
afplayaudio cue is hardcoded. On Linux or Windows, this simply won't run. skeledrew's note that cross-platform support is "pretty trivial" is accurate from a technical standpoint, but it hasn't been done yet. If you're not on macOS, watch the repo. - 120 stars, 49 commits, one release. The science is solid and the author is technically careful, but the project is 24 hours old. Treat it like early-stage software — it's stable enough to use daily, but don't build workflows around the CLI interface being frozen.
- Wellness tool, not medical device. The clinical literature supports resonance breathing for HRV and baroreflex sensitivity. breathe-cli does not diagnose, monitor, or treat anything. If you have a cardiac condition, talk to your doctor before adding any paced breathing protocol.
- Reddit and Twitter are silent. No organic community posts beyond the HN thread as of this writing. 2 Adoption is purely HN-driven right now.
Verdict
breathe-cli is a clean, honest tool doing one thing backed by two decades of cardiology research. The macOS constraint is a real limitation, but if you're on a Mac and you've ever thought "I should do some box breathing" and then not done it because opening an app is too much overhead — this is exactly the install you want.
The clinical motivation behind the design constraints gives it a different character than most wellness tools, which layer features to justify their presence on the App Store. Here, the safety rules exist because the author has a heart condition and checked the literature. That's a rare trait in a 15 KB pip package.
Try it now:
pip install breathe-cli && breatheCover image: breathe-cli GitHub repository social card from marekkowalczyk/breathe-cli
围绕这条内容继续补充观点或上下文。