vibe-wellness

macOS python

I vibe-code 8+ hours a day. Hours disappear, my back hurts, I forget to drink water. Sound familiar?

Your AI pair programmer doesn't need to stretch. You do.

demo

vibe-wellness is a native macOS overlay that hooks directly into Claude Code to remind you to move, stretch, and hydrate — inside your workflow, not as notifications you'll ignore.

3-second countdown with exercise name
Animated stick figure GIF showing the exercise
Progress bar + auto-dismiss after 30 seconds (or click to dismiss)

30-second setup

One-liner:

curl -fsSL https://raw.githubusercontent.com/odysa/vibe-wellness/main/install.sh | bash

Or with uv:

uvx vibe-wellness

Both methods will:

Install vibe-wellness via uv tool install
Run the interactive setup wizard (language, interval, exercises, hook)
Create a hook script at ~/.claude/hooks/vibe-wellness/show.sh
Register the hook in ~/.claude/settings.json

Re-configure

Run vibe-wellness again to change settings.

Exercises

Key	English	中文
`kegels`	Kegels	提肛
`drink_water`	Drink Water	喝水
`squats`	Squats	深蹲
`wall_pushups`	Wall Push-ups	靠墙俯卧撑
`neck_rolls`	Neck Rolls	颈椎运动

All exercises include animated stick figure GIFs.

Configuration

Edit ~/.config/vibe-wellness/config.json:

{
  "lang": "zh",
  "interval": 15
}

Key	Default	Description
`lang`	`"auto"`	`"en"`, `"zh"`, or `"auto"` (detect system)
`interval`	`15`	Minutes between exercise reminders
`duration`	`30`	Overlay display time in seconds
`opacity`	`0.95`	Window opacity (0.0 - 1.0)
`exercises`	(built-in)	Custom exercise list
`sedentary.enabled`	`true`	Enable sedentary reminder
`sedentary.interval`	`30`	Minutes between sedentary alerts

Custom exercises

Exercises merge with defaults by key:

{
  "exercises": [
    { "key": "stretching", "name": { "en": "Stretch", "zh": "拉伸" } }
  ]
}

Custom GIFs

Drop {key}.gif in ~/.config/vibe-wellness/gifs/ to override any exercise animation.

Uninstall

vibe-wellness --uninstall

How it works

~/.claude/settings.json          Hook triggers on UserPromptSubmit/Stop/Notification
  -> ~/.claude/hooks/vibe-wellness/show.sh
    -> ~/.local/bin/vibe-wellness --show
      -> checks interval + single-instance lock
      -> spawns overlay (tkinter, borderless, always-on-top)

vibe_wellness/
  cli.py          Entry point
  installer.py    Interactive setup wizard (TUI)
  show.py         Single-instance guard + interval check
  ui.py           Overlay window (tkinter + CoreGraphics + ObjC runtime)
  config.py       Config loading, i18n, language detection
  uninstall.py    Clean removal
  config.json     Default exercises
  gifs/           Bundled exercise GIFs

Release files for vibe-wellness 0.4.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vibe-wellness 0.4.6
File	Size	Uploaded
vibe_wellness-0.4.6.tar.gz	1.2 MB	Mar 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for vibe-wellness 0.4.6
File	Interpreter	ABI	Platform	Reset
vibe_wellness-0.4.6-py3-none-any.whl 188.7 kB Mar 7, 2026	Python 3	none	any	Details

Total release size: 1.4 MB

Release files / vibe_wellness-0.4.6.tar.gz

Download URL	vibe_wellness-0.4.6.tar.gz
Size	1.2 MB
Tags	Source
SHA-256 checksum How to use checksums	`350d838baa8b7a5cff9fd3a3a2189f7867caa79036c188f393db9b2c056a6125`
BLAKE2b-256 checksum How to use checksums	`0d336a20e969dffbc0f2e880b36cc07d8cf7acb48ed0b15ed404081d661c5590`
Upload date	Mar 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/odysa/vibe-wellness
Publishing commit: github.com/odysa/vibe-wellness/tree/86f9949b77a1c5898beac15be8539369f329c611

Workflow

Publishing configuration: github.com/odysa/vibe-wellness/blob/86f9949b77a1c5898beac15be8539369f329c611/.github/workflows/publish.yml
Publishing logs: github.com/odysa/vibe-wellness/actions/runs/22790594444/attempts/1

Artifact

Subject: vibe_wellness-0.4.6.tar.gz
SHA-256 checksum: 350d838baa8b7a5cff9fd3a3a2189f7867caa79036c188f393db9b2c056a6125 Verifying attestations

Release files / vibe_wellness-0.4.6-py3-none-any.whl

Download URL	vibe_wellness-0.4.6-py3-none-any.whl
Size	188.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`788ad6db224445ecdb831e1b7b9697f9a206bcd5ac085b76f0080babf65fd99a`
BLAKE2b-256 checksum How to use checksums	`7ccfee192a1f7ee3410b3a2d3f9869c6dd1fe08efa738a1c1213b56e9fb08b55`
Upload date	Mar 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/odysa/vibe-wellness
Publishing commit: github.com/odysa/vibe-wellness/tree/86f9949b77a1c5898beac15be8539369f329c611

Workflow

Publishing configuration: github.com/odysa/vibe-wellness/blob/86f9949b77a1c5898beac15be8539369f329c611/.github/workflows/publish.yml
Publishing logs: github.com/odysa/vibe-wellness/actions/runs/22790594444/attempts/1

Artifact

Subject: vibe_wellness-0.4.6-py3-none-any.whl
SHA-256 checksum: 788ad6db224445ecdb831e1b7b9697f9a206bcd5ac085b76f0080babf65fd99a Verifying attestations