Mindful Claude: a Claude Code Breathing Exercise While You Wait

Mindful Claude is a community mod by Anthony (halluton). It turns the time you spend waiting for Claude into a short guided Claude Code breathing exercise. When Claude starts working, a nine-row breathing animation appears above the input box, with a phase line such as Breathe in... 4s and the exercise name under it. At the same time the spinner word changes to the breath, so it reads Breathe in 4s… instead of its usual text. When Claude answers, the band disappears.

The author's reasoning, from the README: slow breathing at about 5.5 breaths per minute raises heart rate variability, so every Claude turn becomes a small breathing session without leaving the terminal. There are four exercises (Coherent Breathing, Physiological Sigh, Box Breathing and 4-7-8 Breathing) and four animation styles (pulse, ripples, dots and wave). By default the style is picked at random for each turn, never the same one twice in a row. A /breathe slash command changes the settings, and they persist across sessions. The README says it needs Claude Code 2.1.269 or later.

The recording starts Claude Code with the mod loaded and asks Claude to read three files and describe the project. While the turn runs, the breathing band above the prompt expands and contracts with a Breathe in… 5s label (the default Coherent Breathing pattern), and the spinner line follows the same rhythm.

Use any of the methods in the install block; they install straight from the author's own marketplace. Once it is installed, send any prompt and the band appears while Claude works.

The mod has two parts. hooks/register.tsx is the hooks module: it remembers when the turn started and hooks the AbovePrompt render site. When the engine reports that a turn is working, it mounts a client surface module, hooks/breathe.tsx, which draws the animation ten times a second on its own clock. Here is the render hook from hooks/register.tsx:

on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
  if (e.surface !== 'terminal' || !config.enabled || !e.props.isWorking || e.props.hasSurvey) return next(e)
  const now = await $.clock.now()
  const running = turn ?? (turn = { startedAt: now, style: pickStyle(config.style, lastStyle) })
  const elapsedMs = now - running.startedAt
  if (elapsedMs < config.delay * 1000) return next(e)
  const { Box, Client } = $.ui.resolve(e)
  // ...
  return (
    <Box flexDirection="column">
      <Client key={key} module="./breathe.tsx" width={e.viewport?.columns ?? 80} height={rows}
        props={{ exercise: config.exercise, style: running.style, elapsedMs }} />
      {await next(e)}
    </Box>
  )
})

The band is keyed by the turn's start time, so each turn gets a fresh animation. Whenever the phase line changes, the surface posts the current word back with surface.post. The hooks module receives it in a ui.message hook and passes it to a second render hook on the Spinner component, which replaces the spinner's message prop. The turn.complete hook clears the turn, so the band goes away as soon as Claude answers. The exercises, the easing curve and the shapes live in hooks/breath/ as pure functions.

Everything is set with the /breathe command, which the mod registers on session.start:

• /breathe shows the current settings, and /breathe help lists every option.
• /breathe on / off shows or hides the band.
• /breathe hrv, sigh, box or 478 picks the exercise.
• /breathe style wave pins one style (pulse, ripples, dots, wave), and /breathe style random goes back to the default.
• /breathe delay 5 waits five seconds into a turn before showing the band, so quick answers stay quiet.
• /breathe spinner off leaves the spinner text alone.

Settings are saved with $.store under one config key and read back at the next session start.

We read every file the plugin loads before we ran it. The plugin uses only UI, clock, command and store calls: no $.process.run, no network, no file access. It does not read your code, prompts or transcript. Its settings are stored in the mod's own $.store, and it never edits settings.json or shell rc files. Changes the UI covers the band and the rewritten spinner word; Adds commands/tools covers /breathe, and Stores data covers the saved settings.

The repository also contains a legacy/ folder with the original bash and tmux version. The plugin does not load it. Its install.sh edits ~/.claude/settings.json and writes to ~/.claude/mindful/, so only run it if you want the old version. claude plugin validate reports one warning: the plugin name contains "claude", which the validator says reads like an Anthropic plugin. It is a naming notice, not a problem with the code.

We validated it with Claude Code 2.1.291 on macOS, and the author's 31 bun test unit tests pass. claude plugin test cannot load them because they import bun:test. If the band does not show up:

• Check that claude --version is 2.1.269 or later. The author's README also asks you to set CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 in the env block of ~/.claude/settings.json.
• Run /breathe and check that it says breathe: on and delay 0s.
• The band is only drawn in the terminal. It also steps aside while a survey is open above the prompt.
• After installing into a session that is already open, run /reload-plugins.