https://github.com/peterklingelhofer/exhale
A customizable visual prompt tool in the form of a screen overlay to facilitate breathwork practice
https://github.com/peterklingelhofer/exhale
breath breathe breathing breathwork electron exercise mac mindfulness osx practice python swift typescript windows
Last synced: 23 days ago
JSON representation
A customizable visual prompt tool in the form of a screen overlay to facilitate breathwork practice
- Host: GitHub
- URL: https://github.com/peterklingelhofer/exhale
- Owner: peterklingelhofer
- License: mit
- Created: 2023-02-27T00:37:26.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2026-01-10T23:45:45.000Z (about 1 month ago)
- Last Synced: 2026-01-11T06:32:32.547Z (about 1 month ago)
- Topics: breath, breathe, breathing, breathwork, electron, exercise, mac, mindfulness, osx, practice, python, swift, typescript, windows
- Language: Swift
- Homepage:
- Size: 5.65 MB
- Stars: 31
- Watchers: 2
- Forks: 6
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# exhale
## Introduction
Research indicates we blink less and breathe more shallowly when we are looking at screens. This minimal app is an internal tool I created for myself that I released for the public in case others find it useful, and is intended as a friendly indicator and reminder to continue to take full and deep breaths. As looking at screens for long periods of time is typically less than ideal, this tool is intended as a means to potentially ameliorate those negative impacts.
Each of these implementations allows users to set an inhale, inhale hold, exhale, and exhale hold duration, in seconds, to fit their needs. For beginners who might be curious what a good starting value might be for these, I recommend keeping it simple, using `4` for the in duration and `4` for the out duration. Eventually you can work your way up to `6` and `8`, and set the out duration to be twice that of the in duration to facilitate activation of the parasympathetic nervous system. Some users might like to start out with box breathing, which is inhale `4`, inhale hold `4`, exhale `4`, exhale hold `4`. Remember, if intense feelings arise while practicing, taking a break is encouraged - it's important to not overdo it.
## Disclaimer
The information and guidance provided by this breathing app are intended for general informational purposes only and should not be construed as medical advice, diagnosis, or treatment. The creator of this app is not a medical professional, and the app is not a substitute for professional medical advice or consultation with a qualified healthcare provider. Always seek the advice of a physician or other qualified healthcare provider with any questions you may have regarding a medical condition or health objectives. Do not disregard or delay seeking professional medical advice because of the information or suggestions provided by this app. In the event of a medical emergency, call your doctor or dial your local emergency number immediately. Use of this app is at your own risk, and the creator assumes no responsibility for any adverse effects or consequences resulting from its use.
## Download
[
](https://apps.apple.com/us/app/exhale-breath/id6447758995?mt=12)
You can download the build for your respective operating system on the [Releases](https://github.com/peterklingelhofer/exhale/releases) page. Using the latest release is recommended, but if you run into issues you could try a previous release to see if that yields better results. If you do encounter a problem, please [document the issue you encountered](https://github.com/peterklingelhofer/exhale/issues/new).
## Mac App Usage
Note: This is built natively in Swift.
To launch the app on Catalina or newer for the first time, you may have to right click and select "Open" instead of double clicking on it, and you may need to do this twice. That's Apple's take on "security" for non-notarized binaries, or if you are not connected to the Internet.
You can use Ctrl + Shift + , to toggle settings open and closed. The **Tint** feature (or Pause) can be used to tint your screen the color of your selected background color, or make your screen darker than otherwise possible for nighttime work (which can compound with both [Night Shift](https://support.apple.com/en-us/102191) and [f.lux](https://justgetflux.com/).
#### Global Keyboard Shortcuts:
Ctrl + Shift + A: **Start Animation**
Ctrl + Shift + S: **Stop Animation**
Ctrl + Shift + D: **Tint Screen**
Ctrl + Shift + F: **Reset to Defaults**
Ctrl + Shift + W or
Ctrl + Shift + ,: **Open/Close Preferences**
**Notice:** A high opacity value can obscure the Preferences pane in the current workspace.
To change this value back, you can use Ctrl + Shift + F to **Reset to Defaults**, or if you'd like to persist your other settings:
1. Swipe left or right with four fingers on your trackpad to switch to a different workspace, or four finger swipe up and select an alternate workspace at the top.
2. From the top bar menu, click Preferences to close the Preferences pane in the previous workspace.
3. Access the top bar menu again, click Preferences to open the Preferences pane in the current workspace, and adjust your Opacity value accordingly.
4. Switch back to the original workspace.
#### Development
```sh
git clone https://github.com/peterklingelhofer/exhale.git
cd exhale
cd swift
xed .
```
## Windows & Linux App Usage
Note: This implementation is built with TypeScript & Electron. The macOS will build but it is not very performant and is far more CPU-intensive than the native Swift build, and as a result the Swift build is recommended for macOS users.
Modify settings by going to **Application** (found in the top right via `>>`) > **Local storage** > **file://**. While the Developer Tools are open, you can resize the window, and opacity values are ignored, so you can position the window and change settings to your liking, and then close the Dev Tools window by clicking the `x` in the top right, or use F12 or Ctrl + Shift + I(Linux/Windows) or Cmd + Shift + I (macOS) to toggle Developer Tools to [access and modify these settings](https://developer.chrome.com/docs/devtools/storage/localstorage/#edit), and Ctrl + R (Linux/Windows) or Cmd + R (macOS) to refresh the app to use your newly selected settings. If no settings appear on the first run of the application, you can manually add them), following the format of the `storedValues` variable in [`/src/renderer.ts`](https://github.com/peterklingelhofer/exhale/blob/main/src/renderer.ts). To add them manually, go to the **Console** and copy paste the following code into the console and press Enter or Return to populate your `localStorage` (these are the defaults as of the time of writing):
```ts
localStorage = {
colorExhale = "rgb(0, 0, 255)",
colorInhale = "rgb(255, 0, 0)",
colorStyle = "linear", // can be "linear" or "constant"
shape = "fullscreen", // can be "circle" or "rectangle" or "fullscreen"
durationInhale = 5,
durationPostInhalePause = 0,
durationExhale = 10,
durationPostExhalePause = 0,
opacity = 0.25,
};
```
Once added, you can modify all values from the **Local Storage** pane. Or, if you prefer the terminal, in the **Console** you can write `localStorage.opacity = "0.15"` for example.
#### Development
```sh
git clone https://github.com/peterklingelhofer/exhale.git
cd exhale
cd typescript
pnpm install
pnpm start
```
To recompile automatically and use [electron-reload](https://github.com/yan-foto/electron-reload), run in a separate terminal:
```sh
pnpm watch
```
## Python Script Usage
Note: This implementation seems to work well on Windows and macOS, but not Linux for some reason.
```sh
git clone https://github.com/peterklingelhofer/exhale.git
cd exhale
cd python
python main.py
```
Modify variables at the top of the file for preferred in and out duration, in seconds.
For the full-screen resizable version, use, `IS_FULL_SCREEN = True` which makes the window entirely resizable by clicking and dragging from the corners.
## Perl Script
Companion repository made in Perl can be found [here](https://github.com/franco3445/Breathing).