Claude Code Task Timer

在 Claude Code 状态栏实时显示当前任务的执行时间。

功能特性

• 实时显示：任务执行过程中显示已用时间
• 完成状态：任务完成后显示总耗时
• 自动恢复计时：Plan 模式 clear context 后执行计划时自动开始计时（通过 PreToolUse Hook）
• 多实例支持：多个 Claude Code 会话独立计时

版本选择

提供 Bash 和 Python 两种实现，功能完全一致，选择其一即可。

版本	适合场景	依赖
Bash 版 (timing_hook.sh)	Linux/macOS，或已有良好 Bash 环境	Bash
Python 版 (timing_hook.py)	Windows（Git Bash 启动开销大），或偏好 Python	Python 3

Python 版启动更快，推荐 Windows 用户使用。

使用方式

方式	实时显示	完成时显示	额外依赖
ccstatusline + Hooks（推荐）	✓	✓	ccstatusline
仅 Hooks	✗	✓	无

安装步骤

1. 复制 Hook 脚本

将 hooks/timing_hook.sh（或 .py）复制到 ~/.claude/hooks/ 目录。

2. 配置 Claude Code Hooks

编辑 ~/.claude/settings.json，添加以下配置（根据版本替换命令）：

Bash 版 — bash ~/.claude/hooks/timing_hook.sh

Python 版 — python ~/.claude/hooks/timing_hook.py

{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "<对应版本的命令>"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "<对应版本的命令>"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "<对应版本的命令>"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "<对应版本的命令>"
          }
        ]
      }
    ]
  }
}

完整配置示例见 examples/claude-settings.jsonc。

3. 配置 ccstatusline（可选，启用实时显示）

如不需要实时显示，可跳过此步，直接参考下方「仅 Hooks 模式」。

安装 ccstatusline：参考 ccstatusline 完成安装和基础配置。

添加 custom-command 组件：

ccstatusline 不支持 ~ 和 $HOME 展开。Windows 使用 %USERPROFILE%，Linux/macOS 使用 $HOME。

{
  "type": "custom-command",
  // Windows Bash 版: "bash %USERPROFILE%/.claude/hooks/timing_hook.sh"
  // Windows Python 版: "python %USERPROFILE%/.claude/hooks/timing_hook.py"
  // Linux/macOS Bash 版: "bash $HOME/.claude/hooks/timing_hook.sh"
  // Linux/macOS Python 版: "python $HOME/.claude/hooks/timing_hook.py"
  "commandPath": "<对应版本和平台的命令>",
  "timeout": 2000
}

完整配置示例见 examples/ccstatusline-settings.jsonc。

已知限制：ccstatusline 的刷新频率受 Claude Code 自身限制，刷新时间不可控，可能会有数秒的滞后。

仅 Hooks 模式

不使用 ccstatusline，仅在任务完成时由 Claude 输出耗时信息。需要取消脚本中 decision:block 相关行的注释：

Bash 版 — 取消 timing_hook.sh 第 114 行的注释：

# 修改前（注释状态）
# echo "{\"decision\": \"block\", \"reason\": \"本次任务耗时: ${DURATION_STR}\"}"

# 修改后（启用）
echo "{\"decision\": \"block\", \"reason\": \"本次任务耗时: ${DURATION_STR}\"}"

Python 版 — 取消 timing_hook.py 第 116 行的注释：

# 修改前（注释状态）
# print(json.dumps({"decision": "block", "reason": f"本次任务耗时: {duration_str}"}))

# 修改后（启用）
print(json.dumps({"decision": "block", "reason": f"本次任务耗时: {duration_str}"}))

工作原理：利用 Stop Hook 的 decision:block 机制——任务完成时 Stop Hook 首次触发，计算耗时并返回 block 决策，Claude Code 读取后输出耗时信息；Stop Hook 第二次触发时检测到已处理过，直接放行。

显示格式

ccstatusline 模式

状态	显示	示例
执行中	RUNNING: {时间}	RUNNING: 1m23s
已完成	DONE: {时间}	DONE: 2m45s

仅 Hooks 模式

任务完成时输出：本次任务耗时: XmXs

时间格式：Xs / XmXs / XhXmXs

故障排除

计时器不显示（Bash 版）

chmod +x ~/.claude/hooks/timing_hook.sh

计时器不显示（Python 版）

确认 python 命令可用：

python --version

时间显示异常

rm -rf ~/.claude/.timing/*

License

MIT License