Mindful Claude: mod de respiración para Claude Code mientras trabaja

Mindful Claude es un mod de respiración para Claude Code, creado por la comunidad: su autor es Anthony (halluton). Convierte el tiempo que pasas esperando a Claude en un breve ejercicio de respiración guiada. Cuando Claude empieza a trabajar, aparece una animación de respiración de nueve filas sobre el cuadro de entrada, con una línea de fase como Breathe in... 4s y el nombre del ejercicio debajo. Al mismo tiempo, la palabra del spinner cambia para seguir la respiración, de modo que dice Breathe in 4s… en lugar de su texto habitual. Cuando Claude responde, la franja desaparece.

El razonamiento del autor, según el README: respirar despacio, a unas 5,5 respiraciones por minuto, aumenta la variabilidad de la frecuencia cardiaca, así que cada turno de Claude se convierte en una pequeña sesión de respiración sin salir de la terminal. Hay cuatro ejercicios (Coherent Breathing, Physiological Sigh, Box Breathing y 4-7-8 Breathing) y cuatro estilos de animación (pulse, ripples, dots y wave). Por defecto el estilo se elige al azar en cada turno, sin repetir nunca el mismo dos veces seguidas. Un comando de barra, /breathe, cambia la configuración, que se conserva entre sesiones. El README indica que necesita Claude Code 2.1.269 o posterior.

La grabación inicia Claude Code con el mod cargado y pide a Claude que lea tres archivos y describa el proyecto. Mientras se ejecuta el turno, la franja de respiración sobre el prompt se expande y se contrae con la etiqueta Breathe in… 5s (el patrón predeterminado, Coherent Breathing), y la línea del spinner sigue el mismo ritmo.

Usa cualquiera de los métodos del bloque de instalación; instalan directamente desde el marketplace del propio autor. Una vez instalado, envía cualquier prompt y la franja aparecerá mientras Claude trabaja.

El mod tiene dos partes. hooks/register.tsx es el módulo de hooks: recuerda cuándo empezó el turno y se engancha al punto de renderizado AbovePrompt. Cuando el motor informa de que un turno está en marcha, monta un módulo de superficie de cliente, hooks/breathe.tsx, que dibuja la animación diez veces por segundo con su propio reloj. Este es el hook de renderizado de 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>
  )
})

La franja usa como clave la hora de inicio del turno, así que cada turno recibe una animación nueva. Cada vez que cambia la línea de fase, la superficie envía la palabra actual de vuelta con surface.post. El módulo de hooks la recibe en un hook de ui.message y la pasa a un segundo hook de renderizado sobre el componente Spinner, que sustituye la prop message del spinner. El hook de turn.complete borra el turno, de modo que la franja desaparece en cuanto Claude responde. Los ejercicios, la curva de suavizado y las formas están en hooks/breath/ como funciones puras.

Todo se ajusta con el comando /breathe, que el mod registra en session.start:

• /breathe muestra la configuración actual, y /breathe help lista todas las opciones.
• /breathe on / off muestra u oculta la franja.
• /breathe hrv, sigh, box o 478 elige el ejercicio.
• /breathe style wave fija un estilo (pulse, ripples, dots, wave), y /breathe style random vuelve al valor predeterminado.
• /breathe delay 5 espera cinco segundos dentro de un turno antes de mostrar la franja, para que las respuestas rápidas no se vean interrumpidas.
• /breathe spinner off deja el texto del spinner como está.

La configuración se guarda con $.store bajo una única clave config y se vuelve a leer en el siguiente inicio de sesión.

Leímos todos los archivos que carga el plugin antes de ejecutarlo. El plugin solo usa llamadas de interfaz, reloj, comandos y almacenamiento: nada de $.process.run, nada de red, nada de acceso a archivos. No lee tu código, tus prompts ni la transcripción. Su configuración se guarda en el $.store propio del mod, y nunca edita settings.json ni los archivos rc de la shell. Modifica la interfaz cubre la franja y la palabra reescrita del spinner; Añade comandos/herramientas cubre /breathe, y Guarda datos cubre la configuración guardada.

El repositorio también contiene una carpeta legacy/ con la versión original en bash y tmux. El plugin no la carga. Su install.sh edita ~/.claude/settings.json y escribe en ~/.claude/mindful/, así que ejecútalo solo si quieres la versión antigua. claude plugin validate informa de un aviso: el nombre del plugin contiene "claude", lo que según el validador parece un plugin de Anthropic. Es un aviso sobre el nombre, no un problema del código.

Lo validamos con Claude Code 2.1.291 en macOS, y los 31 tests unitarios de bun test del autor pasan. claude plugin test no puede cargarlos porque importan bun:test. Si la franja no aparece:

• Comprueba que claude --version es 2.1.269 o posterior. El README del autor también pide definir CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 en el bloque env de ~/.claude/settings.json.
• Ejecuta /breathe y comprueba que dice breathe: on y delay 0s.
• La franja solo se dibuja en la terminal. También se aparta mientras hay una encuesta abierta sobre el prompt.
• Después de instalar en una sesión que ya estaba abierta, ejecuta /reload-plugins.