mindful-claude

mindful-claude fills the seconds you spend waiting on Claude with a guided breathing exercise. When a turn starts, a breathing animation appears above the Claude Code prompt and the spinner line shows the same phase and countdown, Breathe in 3s. When Claude answers, both are gone. Nothing goes to the model, so it costs zero tokens.

What it does

• Four exercises: Coherent Breathing (5.5s in, 5.5s out), Physiological Sigh (4s in, a 1s second sip, 10s out), Box Breathing (4s in, 4s hold, 4s out, 4s hold) and 4-7-8 Breathing (4s in, 7s hold, 8s out). Coherent Breathing is the default; the author cites its rate, about 5.5 breaths a minute, as raising heart rate variability.
• Four animation styles: pulse, ripples, dots and wave. By default each turn gets one at random, never the one just shown.
• The spinner’s word becomes the current phase and its countdown, so the breath stays readable when you are not looking at the band.
• /breathe shows the current settings and /breathe help lists every option. /breathe hrv, sigh, box or 478 switches exercise. /breathe style wave pins a style and random restores the draw. /breathe delay 5 waits five seconds into a turn before drawing the band. /breathe spinner off leaves the spinner alone. /breathe off hides the band. The settings survive restarts.

Install

Needs Claude Code 2.1.269 or later with function hooks enabled and an interactive terminal. There is nothing to click or press: the band only draws.

claude plugin marketplace add halluton/Mindful-Claude
claude plugin install mindful-claude@mindful-claude

Start claude and send a prompt. The band appears while Claude works. claude plugin uninstall mindful-claude removes it.

How it works

The hooks module watches turn.start and turn.complete and draws in the band Claude Code gives plugins above the prompt: up to nine rows, seven for the picture, one for the phase line and one for the exercise name. The animation is a Client module with its own frame clock, ten frames a second, so nothing waits on the model. Each time the phase line changes, about once a second, it posts the phase to the hooks module, which rewrites the spinner’s message with it.

It handles only its own /breathe command, reads no prompts, tool calls or files, and makes no network calls. The only thing it stores is its settings (on or off, exercise, style, delay, spinner), in Claude Code’s plugin store on your machine.

An older bash and tmux version of the same idea lives in the repository’s legacy/ folder. The mod replaces it and needs neither tmux nor jq.

Limitations

• Draws only in interactive terminal sessions. Nothing appears in claude -p, the desktop app or mobile.
• The band leaves the moment Claude answers, wherever the breath is.
• When Claude Code gives the band fewer than nine rows, the picture shrinks first; the phase line is the last thing to go.