GitHub - marekkowalczyk/breathe-cli: Paced resonance breathing in your terminal · GitHub
Skip to content
Navigation Menu
Toggle navigation
Sign in
Appearance settings
PlatformAI CODE CREATIONGitHub CopilotWrite better code with AIGitHub SparkBuild and deploy intelligent appsGitHub ModelsManage and compare promptsMCP RegistryNewIntegrate external toolsDEVELOPER WORKFLOWSActionsAutomate any workflowCodespacesInstant dev environmentsIssuesPlan and track workCode ReviewManage code changesAPPLICATION SECURITYGitHub Advanced SecurityFind and fix vulnerabilitiesCode securitySecure your code as you buildSecret protectionStop leaks before they startEXPLOREWhy GitHubDocumentationBlogChangelogMarketplaceView all featuresSolutionsBY COMPANY SIZEEnterprisesSmall and medium teamsStartupsNonprofitsBY USE CASEApp ModernizationDevSecOpsDevOpsCI/CDView all use casesBY INDUSTRYHealthcareFinancial servicesManufacturingGovernmentView all industriesView all solutionsResourcesEXPLORE BY TOPICAISoftware DevelopmentDevOpsSecurityView all topicsEXPLORE BY TYPECustomer storiesEvents & webinarsEbooks & reportsBusiness insightsGitHub SkillsSUPPORT & SERVICESDocumentationCustomer supportCommunity forumTrust centerPartnersView all resourcesOpen SourceCOMMUNITYGitHub SponsorsFund open source developersPROGRAMSSecurity LabMaintainer CommunityAcceleratorGitHub StarsArchive ProgramREPOSITORIESTopicsTrendingCollectionsEnterpriseENTERPRISE SOLUTIONSEnterprise platformAI-powered developer platformAVAILABLE ADD-ONSGitHub Advanced SecurityEnterprise-grade security featuresCopilot for BusinessEnterprise-grade AI featuresPremium SupportEnterprise-grade 24/7 supportPricing
Search or jump to...
Search code, repositories, users, issues, pull requests...
Search
Clear
Search syntax tips
Provide feedback
We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.
You signed out in another tab or window. Reload to refresh your session.
You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
marekkowalczyk
/
breathe-cli
Public
Notifications
You must be signed in to change notification settings
Fork
0
Star
1
Code
Issues
0
Pull requests
0
Discussions
Actions
Projects
Security and quality
0
Insights
Additional navigation options
Code
Issues
Pull requests
Discussions
Actions
Projects
Security and quality
Insights
marekkowalczyk/breathe-cli
masterBranchesTagsGo to fileCodeOpen more actions menuFolders and filesNameNameLast commit messageLast commit dateLatest commit History47 Commits47 Commitsdevdev .gitignore.gitignore CLAUDE.mdCLAUDE.md LICENSELICENSE README.mdREADME.md _config.yml_config.yml breathe.pybreathe.py google42e5de7281e23ce0.htmlgoogle42e5de7281e23ce0.html pyproject.tomlpyproject.toml social-card.pngsocial-card.png test_breathe.pytest_breathe.py View all filesRepository files navigationREADMEMIT licenseBreathe CLI
A terminal app that paces resonance breathing for vagal tone training. macOS only, single file, no dependencies.
$ breathe
calm · 4-6 · 14:32 [●]
INHALE
██████████████░░░░░░░░░░░░░░░░
space pause · s mute · q quit
Why this exists
Resonance breathing — slow, paced breathing at around 6 breaths per minute — is one of the few non-pharmacological interventions shown to improve cardiac vagal tone. The mechanism is straightforward: slow breathing amplifies respiratory sinus arrhythmia (RSA), the natural heart-rate variation linked to the breath cycle. Stronger RSA means stronger vagal outflow, which in turn improves baroreceptor sensitivity and shifts autonomic balance away from sympathetic dominance.
This matters most for people with heart failure with reduced ejection fraction (HFrEF), where sympathetic overdrive is both a symptom and an accelerant of disease progression. Bernardi et al. (1998) demonstrated that slow breathing at 6 bpm improves oxygen saturation and exercise tolerance in CHF patients, with effects visible after a single session. A follow-up study (Bernardi et al. 2002) showed that slow breathing also increases arterial baroreflex sensitivity in CHF — a marker strongly associated with prognosis.
This app is a habit tool that makes daily practice frictionless: open terminal, run breathe, follow the bar. It is not a medical device.
The science in brief
Why 6 breaths per minute? The cardiovascular system has a resonance frequency — typically between 4.5 and 6.5 bpm in adults — at which heart rate oscillations are maximally amplified (Vaschillo et al. 2006). Breathing at or near this frequency produces the largest RSA swings, which drive the strongest vagal training stimulus. Individual resonance frequency varies and can only be identified precisely with HRV biofeedback hardware. Without it, 6 bpm is the best population-level default: it sits at the centre of the typical range and matches the rate used in the CHF clinical trials (Bernardi et al. 1998, 2002).
Why a longer exhale in the calm and extended presets? Cardiac vagal efferent activity is gated to the respiratory cycle — vagal outflow is stronger during expiration than inspiration. A longer exhale (4s in, 6s out) extends the phase of peak vagal drive within each breath, biasing the autonomic balance further toward parasympathetic tone (Russo et al. 2017, Lehrer & Gevirtz 2014). The total cycle is still 10 seconds (6 bpm). The balanced preset uses equal timing (5-5) as a neutral baseline; the calm and extended presets use the exhale-weighted ratio for parasympathetic emphasis.
Why these safety constraints? See the Design choices section below. Each constraint maps to a specific physiological risk that is elevated in cardiac patients.
Finding your resonance frequency
The presets use 6 bpm because it works well for most people and matches the clinical trial protocols. But individual resonance frequency varies — typically between 4.5 and 6.5 bpm — and breathing at your resonance frequency produces a stronger vagal training stimulus than breathing at the population average (Vaschillo et al. 2006).
If you have HRV biofeedback hardware, you can find your personal optimum. If you don't, the 6 bpm default is a good choice — consistent daily practice matters more than nailing the exact frequency.
What you need
A chest-strap heart rate monitor (e.g. Polar H10, Garmin HRM-Pro). Wrist-based optical sensors are not accurate enough for beat-to-beat HRV.
Software that displays real-time R-R intervals or HRV metrics: Kubios, Elite HRV, HRV4Training, or a dedicated biofeedback system.
Protocol
Run this test sitting upright in a quiet room, at the same time of day you normally practice. The whole procedure takes about 30 minutes.
Baseline (2 min). Breathe normally. Let your heart rate settle. Start your HRV recording.
Test rate 1: 6.0 bpm (3 min). Run breathe --ratio 5-5 -d 3 --no-log. Follow the pacer. At the end, note the average RMSSD (or, if your software shows a live heart rate trace, note how wide the oscillations are — peak-to-trough in bpm).
Rest (1–2 min). Breathe normally.
Test rate 2: 5.5 bpm (3 min). Run breathe --ratio 5-6 -d 3 --no-log. Note the same metric.
Rest (1–2 min).
Test rate 3: 5.0 bpm (3 min). Run breathe --ratio 6-6 -d 3 --no-log. Note the same metric.
Rest (1–2 min).
Test rate 4: 4.6 bpm (3 min). Run breathe --ratio 6-7 -d 3 --no-log. Note the same metric.
Interpreting results: The rate that produces the highest RMSSD, the highest LF power in the HRV spectrum, or the visibly widest heart rate oscillations is your resonance frequency. If two adjacent rates are close, pick the slower one — it's more comfortable for long sessions.
Limitations: Phase durations are whole seconds, so only certain BPMs are representable: 4.6, 5.0, 5.5, 6.0, 6.7, 7.5 bpm. Your true resonance might fall between two testable rates. Pick the closest one. The difference in training effect between 5.0 and 5.5 bpm is small.
Using your frequency
Once you know your frequency, use --ratio to match it:
breathe --ratio 6-7 # 13s cycle = 4.6 bpm
breathe --ratio 6-6 # 12s cycle = 5.0 bpm
breathe --ratio 5-6 # 11s cycle = 5.5 bpm
breathe --ratio 5-5 # 10s cycle = 6.0 bpm (default)
You can also add exhale emphasis at your resonance frequency:
breathe --ratio 5-7 # 12s cycle = 5.0 bpm, exhale-weighted
breathe --ratio 4-7 # 11s cycle = 5.5 bpm, exhale-weighted
breathe --ratio 4-8 # 12s cycle = 5.0 bpm, strong exhale emphasis
References
Bernardi L, Spadacini G, Bellwon J, et al. "Effect of breathing rate on oxygen saturation and exercise performance in chronic heart failure." Lancet. 1998;351(9112):1308-1311.
Bernardi L, Porta C, Spicuzza L, et al. "Slow breathing increases arterial baroreflex sensitivity in patients with chronic heart failure." Circulation. 2002;105(2):143-145.
Bernardi L, Sleight P, Bandinelli G, et al. "Effect of rosary prayer and yoga mantras on autonomic cardiovascular rhythms." BMJ. 2001;323:1446.
Vaschillo EG, Vaschillo B, Lehrer PM. "Characteristics of resonance in heart rate variability stimulated by biofeedback." Appl Psychophysiol Biofeedback. 2006;31(2):129-142.
Lehrer PM, Gevirtz R. "Heart rate variability biofeedback: how and why does it work?" Front Psychol. 2014;5:756.
Russo MA, Santarelli DM, O'Rourke D. "The physiological effects of slow breathing in the healthy human." Breathe. 2017;13(4):298-309.
Design choices
This app is deliberately constrained. Several common breathing-app features are excluded for safety and focus:
No breath retention. Breath holds (kumbhaka) raise intrathoracic pressure via a Valsalva-like mechanism and can trigger vasovagal syncope or arrhythmia in cardiac patients. The Bernardi protocols use continuous breathing with no hold phases. The app rejects three-number ratios like 4-7-8 with an explicit safety error.
No rapid breathing. Patterns faster than 7.5 bpm (cycles shorter than 8 seconds) move toward hyperventilation territory, reducing arterial CO2 and mobilising catecholamines — the opposite of the vagal intent (Russo et al. 2017). The app enforces a minimum cycle length of 8 seconds.
No breath holds between phases. There is no pause between inhale and exhale. The breath is continuous, matching the protocol in Bernardi et al. (1998, 2002).
Immediate exit, always. Pressing q or Ctrl+C ends the session within one frame. The terminal is always restored — cursor, colours, input mode — even if the app crashes. The finally block that does this is the most important code in the file.
No dependencies. Single Python file, stdlib only. Nothing to install, nothing to break. Runs on the Python that ships with macOS.
No curses. Direct ANSI escape codes only. The curses library has edge cases with non-default terminals on macOS Mojave.
Requirements
macOS (uses /usr/bin/afplay for audio cues)
Python 3.7+
Installation
# Clone or download breathe.py, then:
chmod +x breathe.py
# Option A: run directly
./breathe.py
# Option B: symlink into your PATH
ln -s "$(pwd)/breathe.py" /usr/local/bin/breathe
breathe
Usage
No arguments — time-of-day auto-select
breathe
With no arguments, the app picks a preset based on the time of day:
Time of day
Preset
Duration
Ratio
BPM
Before noon
balanced
10 min
5s-5s
6
12:00–16:59
extended
20 min
4s-6s
6
17:00+
calm
15 min
4s-6s
6
All presets target 6 breaths per minute. The balanced preset uses equal inhale/exhale (5-5) as a neutral baseline. The calm and extended presets use a longer exhale (4-6), which emphasises vagal activation during the expiratory phase. The time-of-day auto-select picks calm in the evening as a default — but you can use any preset at any time.
Presets
breathe --preset balanced # 10 min, 5s-5s
breathe --preset calm # 15 min, 4s-6s
breathe --preset extended # 20 min, 4s-6s (full Bernardi protocol dose)
breathe --list-presets # show the table
Custom sessions
breathe --duration 5 # 5 minutes, default 5-5 ratio
breathe --ratio 4-6 # default 10 minutes, 4-6 ratio
breathe --duration 12 --ratio 4-6 # 12 minutes, 4-6 ratio
Duration: 1–60 minutes (rounded up to complete breath cycles). Ratio: inhale and exhale each 3–10 seconds, total cycle >= 8 seconds, exhale at most 2x inhale.
Flags
Flag
Short
Description
--preset NAME
-p
Use a named preset
--duration MIN
-d
Session length in minutes (1–60)
--ratio IN-EX
-r
Breath ratio, e.g. 5-5 or 4-6
--no-sound
-n
Disable audio cues
--quiet
-q
Suppress startup warnings
--no-log
Don't log this session
--log
Print log file path and exit
--safety
Print safety information and exit
--list-presets
Print preset table and exit
--version
Print version and exit
Runtime keys
During a session:
Key
Action
space
Pause / resume. Resume restarts from the beginning of INHALE.
s
Toggle sound mute.
q
Quit immediately. Terminal is restored.
Ctrl+C
Same as q.
The display
balanced · 5-5 · 09:12 [●] <- preset, ratio, countdown, status
INHALE <- current phase (cyan) or EXHALE (green)
████████████████░░░░░░░░░░░░░░ <- breath bar (fills on inhale, drains on exhale)
space pause · s mute · q quit <- available controls
The status indicator shows ● during breathing, ‖ when paused, and 🔇 when muted.
The countdown timer tracks completed breathing time only. If you pause for 30 seconds during a 1-minute session, the session takes ~90 seconds of wall-clock time to complete — the timer doesn't advance while paused.
Session logging
Each session appends a row to ~/.breathe_log.csv:
date,time,preset,ratio,duration_target_s,duration_actual_s,breaths,completion_pct,status
2026-05-30,07:15:02,balanced,5-5,600,600,60,100,completed
2026-05-30,19:30:14,calm,4-6,900,420,42,46,ended early (user)
Use --no-log to skip logging for a session. Use --log to see the log file path.
Testing
Automated tests cover logic and arithmetic (formatting, ratio parsing, safety rejections, preset invariants, countdown calculation):
python3 -m unittest test_breathe -v
TUI behaviour (rendering, animation, terminal restoration) is covered by 25 manual acceptance tests in dev/breathe-cli-spec.md.
Safety
Run breathe --safety for the full safety screen. The short version:
Stop immediately if you experience lightheadedness, palpitations, or tingling in your hands or face.
This app deliberately does not support breath retention, rapid breathing, or any pattern not grounded in the slow-breathing clinical literature. These constraints are enforced in the code and cannot be overridden. See The science in brief and Design choices for the clinical rationale.
Disclaimer
This app is not a medical device. It does not diagnose, treat, cure, or prevent any disease or condition. Always consult your physician before starting a breathing practice, especially if you have a cardiac or respiratory condition. Use entirely at your own risk. The author assumes no liability for any adverse effects arising from the use of this software. By using this app you acknowledge that you understand and accept these terms.
License
MIT License. See LICENSE for the full text.
Created by Marek Kowalczyk.
About
Paced resonance breathing in your terminal
marekkowalczyk.github.io/breathe-cli/
Topics
macos
cli
terminal
health
breathing
hrv
heart-rate-variability
biofeedback
heart-failure
vagal-tone
resonance-breathing
Resources
Readme
License
MIT license
Uh oh!
There was an error while loading. Please reload this page.
Activity
Stars
1
star
Watchers
0
watching
Forks
0
forks
Report repository
Releases
1
v1.8 — Science & Safety
Latest
May 30, 2026
Packages
0
Uh oh!
There was an error while loading. Please reload this page.
Contributors
Uh oh!
There was an error while loading. Please reload this page.
Languages
Python
84.8%
HTML
15.2%
Footer
© 2026 GitHub, Inc.
Footer navigation
Terms
Privacy
Security
Status
Community
Docs
Contact
Manage cookies
Do not share my personal information
You can’t perform that action at this time. |
The breathe-cli is a command-line application designed to facilitate paced resonance breathing for training vagal tone, implemented as a dependency-free, single-file utility for macOS. The core objective of the application stems from the physiological principle that slow, paced breathing, specifically at around six breaths per minute, is a non-pharmacological intervention capable of improving cardiac vagal tone. This effect is mediated by amplifying respiratory sinus arrhythmia (RSA), which drives stronger vagal outflow and enhances baroreceptor sensitivity, particularly beneficial for individuals with heart failure with reduced ejection fraction (HFrEF).
The scientific underpinning for the application centers on the concept of cardiovascular resonance. The cardiovascular system exhibits a resonance frequency, typically between 4.5 and 6.5 beats per minute (bpm), where heart rate oscillations are maximally amplified. Breathing near this frequency produces the largest RSA swings, serving as the strongest stimulus for vagal training. While individual resonance frequencies vary, the application defaults to 6 bpm as a clinically relevant population average, consistent with protocols established in cardiac care research by Bernardi et al. (1998, 2002).
The design incorporates specific pacing techniques to modulate autonomic balance. Longer exhales emphasize vagal activity because vagal outflow is stronger during expiration. Presets such as calm and extended utilize ratios that favor the exhale, promoting a shift toward parasympathetic tone. The application allows for user calibration of this experience by assessing individual resonance frequencies. A suggested protocol involves testing breathing rates ranging from 4.6 bpm to 6.0 bpm, recording Heart Rate Variability (HRV) metrics like RMSSD or LF power, and identifying the rate that yields the strongest physiological response. If hardware is unavailable, the 6 bpm default serves as a reliable starting point, as consistent practice is deemed more important than precise frequency identification.
The application enforces strict safety constraints based on these physiological findings. To mitigate risks to cardiac patients, the design explicitly excludes features that could elevate intrathoracic pressure, such as breath retention (kumbhaka) or rapid breathing patterns exceeding 7.5 bpm, which can lead to hyperventilation or vasovagal syncope (Russo et al., 2017). All breathing cycles must maintain a minimum duration of eight seconds, and there must be no pause between the inhale and exhale phases, ensuring continuous breathing that aligns with established clinical protocols.
The user interface provides several operational modes. By default, the application auto-selects a preset based on the time of day, generally defaulting to the calm preset in the evening. Users can initiate custom sessions by defining a duration, such as five to sixty minutes, and a specific ratio for inhalation and exhalation, ensuring the total cycle remains above eight seconds. Runtime controls allow for pausing, muting audio cues, or immediate quitting. Furthermore, the session logging feature records details such as duration, actual time, number of breaths, and completion percentage into a log file for retrospective analysis. The tool is explicitly presented as a habit-forming aid, emphasizing that it is not a medical device and users must consult a physician before employing the practice. |