Mindful Claude：Claude 工作时引导你呼吸的 Claude Code 呼吸练习插件

Mindful Claude 是一款 Claude Code 呼吸练习插件，属于社区插件，作者是 Anthony（halluton）。它把你等待 Claude 的时间变成一次简短的引导式呼吸练习。Claude 开始工作时，输入框上方会出现一个九行高的呼吸动画，下面有一行阶段提示，例如 Breathe in... 4s，以及练习名称。与此同时，加载提示的文字会变成呼吸节奏，显示为 Breathe in 4s…，而不是平常的文字。Claude 回答后，横条就会消失。

作者在 README 中给出的理由是：以每分钟约 5.5 次的速度慢呼吸可以提高心率变异性，因此 Claude 的每一轮对话都能变成一次不离开终端的小型呼吸练习。共有四种练习（共振呼吸、生理性叹息、方块呼吸和 4-7-8 呼吸）以及四种动画样式（pulse、ripples、dots 和 wave）。默认情况下，每轮对话随机选择一种样式，且不会连续两次相同。/breathe 斜杠命令用于修改设置，设置会跨会话保留。README 中写明需要 Claude Code 2.1.269 或更高版本。

录屏中，我们启动加载了该插件的 Claude Code，让 Claude 读取三个文件并描述这个项目。在这一轮运行期间，输入框上方的呼吸横条随着 Breathe in… 5s 标签扩张和收缩（默认的共振呼吸模式），加载提示行也跟着同样的节奏变化。

使用安装区块中的任意一种方式；它们都直接从作者自己的插件市场安装。安装完成后，发送任意提示，Claude 工作期间横条就会出现。

插件分为两部分。hooks/register.tsx 是钩子模块：它记录这一轮开始的时间，并挂接 AbovePrompt 渲染位置。当引擎报告某一轮正在工作时，它会挂载一个客户端界面模块 hooks/breathe.tsx，由该模块按自己的时钟每秒绘制十次动画。以下是 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>
  )
})

横条以这一轮的开始时间作为 key，因此每一轮都会得到一段全新的动画。每当阶段提示变化时，界面模块会用 surface.post 把当前的提示词发回去。钩子模块在 ui.message 钩子中接收它，并传给 Spinner 组件上的第二个渲染钩子，由后者替换加载提示的 message 属性。turn.complete 钩子会清除这一轮的状态，所以 Claude 一回答，横条就会消失。练习、缓动曲线和形状都作为纯函数放在 hooks/breath/ 中。

所有设置都通过 /breathe 命令完成，插件在 session.start 时注册这个命令：

• /breathe 显示当前设置，/breathe help 列出所有选项。
• /breathe on / off 显示或隐藏横条。
• /breathe hrv、sigh、box 或 478 选择练习。
• /breathe style wave 固定使用一种样式（pulse、ripples、dots、wave），/breathe style random 恢复默认。
• /breathe delay 5 在一轮开始五秒后才显示横条，让快速的回答保持安静。
• /breathe spinner off 不改动加载提示的文字。

设置通过 $.store 保存在一个 config 键下，并在下一次会话开始时读回。

在运行之前，我们读过了插件加载的每一个文件。插件只使用界面、时钟、命令和存储相关的调用：没有 $.process.run，没有网络，也没有文件访问。它不读取你的代码、提示或对话记录。它的设置保存在插件自己的 $.store 中，从不修改 settings.json 或 shell rc 文件。修改界面对应的是横条和被改写的加载提示文字；添加命令/工具对应的是 /breathe，存储数据对应的是保存的设置。

仓库中还有一个 legacy/ 文件夹，里面是最初基于 bash 和 tmux 的版本。插件不会加载它。其中的 install.sh 会修改 ~/.claude/settings.json 并写入 ~/.claude/mindful/，所以只有想用旧版本时才运行它。claude plugin validate 报告了一条警告：插件名称中包含 "claude"，验证器认为这读起来像是 Anthropic 的插件。这只是命名提示，不是代码的问题。

我们在 macOS 上使用 Claude Code 2.1.291 完成了验证，作者的 31 个 bun test 单元测试全部通过。claude plugin test 无法加载这些测试，因为它们导入了 bun:test。如果横条没有出现：

• 检查 claude --version 是否为 2.1.269 或更高版本。作者的 README 还要求在 ~/.claude/settings.json 的 env 区块中设置 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1。
• 运行 /breathe，确认显示 breathe: on 和 delay 0s。
• 横条只在终端中绘制。当输入框上方打开着问卷时，它也会暂时让位。
• 安装到已经打开的会话后，运行 /reload-plugins。