Claudoro：Claude 状态栏嵌入番茄工作计时器

背景

Hacker News 上的一篇 Show HN 帖子，展示了 Claude Code 的终端状态行（statusline）中内置的 Pomodoro 计时器工具 Claudoro。该工具无需独立应用或切换窗口，计时器直接嵌入 Claude Code 终端中，与 Claude 代码协作无缝融合。

核心内容

Claudoro 简介与核心功能
Claudoro 是一个 Pomodoro 计时器，完整嵌入 Claude Code 的终端状态行（statusline）。它在用户最常关注的区域（状态行）提供实时滴答计时，并具备即使状态行隐藏或关闭所有会话时仍能触发可靠警报的功能。
无需单独应用、无需切换标签页、无需打破专注度。计时器位于用户已经习惯查看的位置，它在用户与 Claude 协作时持续滴答。
长会话易模糊时间感。现有 Pomodoro 工具（菜单栏应用、浏览器标签页、手机）均位于终端外部，分散注意力。Claudoro 渲染于终端的未使用始终可见表面，无需额外 glance 或上下文切换。

安装要求与方式
安装前提：Node.js 版本 ≥ 22（若通过 npm 安装 Claude Code，已自动包含）。

• 全局安装：npm install -g claudoro
  随后执行 pomo setup。
• 源代码安装（开发/预发布版）：

  git clone https://github.com/emson/claudoro.git
  cd claudoro
  npm install
  npm link  # 创建全局 pomo 二进制文件，指向此 checkout
  pomo setup
  npm link
  

  这使 pomo 命令全局可用，同时保留源目录作为实时副本。后续 git pull 可立即生效，无需重新安装。卸载时执行 npm unlink -g claudoro。

pomo setup 功能
pomo setup 自动将 Claudoro 集成到 Claude Code 中：

• 创建 /pomo 命令文件
• 合并 statusLine 块到 settings.json（会先备份）
• 记录所有修改至清单，便于清理卸载
  操作具备幂等性，可安全重复执行。

核心命令

• pomo start：启动计时器
• pomo start [mins] [-w 25 -s 5 -l 15 -f 4] [-t "my task"]：指定时长、短/长休息时长、长休息频率、任务标签
• pomo pause | resume | stop
• pomo skip：提前结束当前阶段
• pomo reset：重置当前阶段，不改变周期计数
• pomo next：推进等待边界（手动/平衡模式）
• pomo back：撤销上一个阶段过渡（短窗口）
• pomo extend [N]：为当前阶段增加 N 分钟
• pomo status：显示详细状态（已用时间、标签、当日计数、下一个长休息）
• pomo mode [auto|balanced|manual]
• pomo view [minimal|classic|full]
• pomo mute | unmute
• pomo note "text"：为当前块添加标签（支持 #tags）
• pomo tag name：为当前块添加 #tag
• pomo label "text"：替换当前块标签
• pomo log：查看当日已完成块
• pomo stats：查看分析（连续天数、专注热图、顶级标签，--web 显示仪表盘）
• pomo undo [N]：撤销最后 N 条记录（先备份）
• pomo restore <backup-id>：从备份恢复
• pomo guide [--web|--json]：Pomodoro 技巧完整指南（终端读取或网页版）
• pomo version：查看版本
• pomo help [command]

与 Claude Code 的交互方式
无需模型往返 API，可直接在 Claude Code 提示符中使用 ! 执行：

!pomo start 50 "architecture spike"
!pomo status --json

视图模式
三种视图模式，可随时切换：

• 空闲时段隐藏
• 启动/停止从不改变布局
• 现有状态行信息（模型 · 上下文% · git）与 Claudoro 共存，不被覆盖
  周期点（●●○○）显示已完成专注块数，向下一个长休息推进。每日午夜（本地时间）或长休息完成后重置为 ○○○○，新一天从空开始。

时长定制
所有时长可通过标志覆盖（非配置文件）：

• pomo start：默认 25/5/15，4 次循环后长休息
• pomo start 50：专注时长 50 分钟，其他不变
• pomo start -s 10 -l 30：仅调整休息时长
• pomo start 50 -s 10 -l 30 -f 3：全自定义

时长在会话生命周期内固定，需 pomo stop 后再启动新会话。

平衡模式（D-006a）

• pomo mode balanced
• 等待边界时状态行显示 +M:SS 超时时长与下一步
• /pomo next 推进，/pomo back 撤销（短窗口）

数据存储与日志
每完成一个专注块，立即追加不可变记录至每日 JSONL 日志。聚合数据（当日计数、周期位置）从日志派生，undo 永远不会反向同步。

• pomo log：今日日志
• pomo log --date 2026-06-10
• pomo undo 2：先备份再删除（干跑确认）
• pomo restore <backup-id>

隐私与本地优先
完全本地优先：无网络、无账号、无遥测。状态保存在 XDG state dir 下，从不离开机器。详见 SECURITY.md。

新用户指南
pomo guide 为完整独立指南：方法解释、周期运作、坚持规则、处理中断、边缘案例及 Claudoro 缓解措施。

• --web：自包含网页版（无依赖，无网络，离线渲染）
• --json：结构化内容供代理或脚本使用
  终端或浏览器中均可阅读，时间显示本地时区，日志保持 UTC。

统计仪表盘
pomo stats：当前连胜、专注热图、顶级标签、专注按小时分布、结果组成，无需离开终端。

• --web：自包含 HTML 仪表盘（单文件，无依赖），浏览器中打开，时间本地时区显示
• --json：稳定 JSON 供代理使用
  仪表盘位于 ~/.local/state/claudoro/dashboard.html，包含会话标签，视为私有文件，可任意删除，下一运行会重建。

全局控制
一个全局计时器，适用于所有打开的 Claude Code 会话。控制可从任意会话发起，警报只触发一次。
在特定窗格隐藏段落：export CLAUDORO_HIDE=1

与现有状态行的兼容
现有状态行不会消失（Claudoro 与之共存）。若出现问题，pomo uninstall 会恢复 pomo setup 创建的时间戳备份。

自动运行与遗忘处理
默认 auto 模式（pomo mode balanced 切换）。遗忘停止时，pomo next 或 pomo stop 会将实际时长记录为“abandoned”（超出计划 + 30 分钟最大超时时长仅计入专注），真时长保留，pomo log 显示“25m focus (ran 11h 32m, abandoned)”。

关键要点

• 嵌入式设计：Pomodoro 计时器直接渲染于 Claude Code 终端状态行，无独立窗口或上下文切换，成本为零。
• 实时性与可靠性：实时滴答计数（支持 idle 刷新），警报即使状态行隐藏或会话关闭仍触发；现有状态行（模型、上下文、git）不被覆盖。
• 命令行优先：无需 Claude API 往返，可用 ! 直接执行；支持自定义时长、标签、笔记、标签、扩展等 20+ 命令。
• 数据不可变与本地：专注块记录追加至每日 JSONL 每日日志，聚合数据实时派生；全本地、无云、无遥测，状态保存在 XDG 目录。
• 隐私与可复原：undo 先备份，restore 支持；仪表盘为单文件私有 HTML；卸载后自动恢复原始状态行。
• 灵活性：三种视图模式；平衡模式处理等待边界；统计 --web 提供离线浏览器仪表盘；guide 包含完整 Pomodoro 技巧指导。
• 跨会话控制：全局计时器与单一警报；可从任意会话控制；隐藏特定窗格。
• 错误防护：遗忘运行自动标记“abandoned”，专注数据永不夸大。

意义与影响

Claudoro 解决了长代码协作会话中时间模糊的痛点，将 Pomodoro 技巧深度集成 Claude Code 生态，彻底消除终端外工具带来的分心与切换成本。它以零学习成本（单指令 pomo setup）与极致隐私（本地-first、无遥测）为开发者提供专属生产力工具。
从用户反馈与设计看，此类嵌入式工具正推动终端工作流向更沉浸式、专注导向演进，未来类似集成可能成为 Claude Code 等 AI 代码 IDE 的标配，提升开发者长期专注力与工作效率，同时保持数据主权。