Claude Code Light · 状态红绿灯

一个置顶的小悬浮窗，让你不用一直盯着命令行也知道 Claude Code 在干嘛。

🔴 等你确认  ·  🟡 进行中  ·  🟢 已完成  ·  ⚫ 空闲

---

它解决什么问题

Claude Code 跑长任务的时候，你多半已经切到别的窗口去了。等它跑完、或者它卡在一个 权限确认框上等你点头，你都不知道 —— 只能时不时切回去看一眼。

这个小工具把状态搬到屏幕角落：一个三灯红绿灯，永远在最上层，扫一眼就够。

灯	含义	触发时机
🔴 红（快闪）	等你确认	权限请求、Claude 向你提问
🟡 黄（慢呼吸）	进行中	你提交提示词后、每次工具调用前后
🟢 绿（常亮）	已完成	本轮回答结束
⚫ 全灭	空闲	没有活跃会话

开着多个 Claude Code 窗口时，取优先级最高的那个：红 > 黄 > 绿 > 灭， 右上角会显示会话总数。鼠标悬停能看到每个会话分别是什么状态。

依赖

只需要 Python 3.7+，自带 tkinter。没有任何第三方包。

用到的全是标准库：json math os socket sys time threading ctypes tkinter。 不需要 pip install，不需要虚拟环境。

• Windows：官方安装包默认就带 tkinter（安装时那个 "tcl/tk and IDLE" 选项默认勾选）。 Microsoft Store 版也带。
• 目标平台是 Windows。核心逻辑（hooks + 状态文件 + 悬浮窗）本身不挑系统， 但 .vbs 启动器、开机自启、pythonw 免黑框都是 Windows 专有的， 其它平台没测过。

install_hooks.py 会先跑一遍环境检查，缺什么直接告诉你，不会装到一半才失败。

安装

git clone git@github.com:hasong66/Claude-Code-Light.git
cd Claude-Code-Light
python install_hooks.py --autostart    # 装 hooks + 开机自启

不想开机自启就去掉 --autostart。

不能直接拷贝 settings.json 或 .vbs 到别的机器。 里面写的是绝对路径 （python 解释器位置、脚本位置），必须在目标机器上跑一次 install_hooks.py 让它按本机实际路径重新生成 —— 所以 启动红绿灯.vbs 不进版本库。 程序自己没有任何硬编码路径，全部由安装器现算。

装完会生成 启动红绿灯.vbs，双击即可手动启动（静默，不闪黑框）。 settings.json 的改动需要新开一个 Claude Code 会话才生效。

想撤销：

python install_hooks.py --uninstall    # 只摘掉本程序的 hooks，其它配置不动

安装器每次都会先把 ~/.claude/settings.json 备份成 .bak-<时间戳>， 并且是幂等的——重复运行只覆盖自己那几条。

操作

• 左键拖动 挪位置（自动记住）
• 鼠标悬停 看各会话明细
• 右键 菜单：总在最前 / 大小（小·中·大）/ 回到右下角 / 清除所有状态 / 退出

组成

文件	作用
traffic_light.py	悬浮窗本体，轮询状态文件并渲染
cc_hook.py	hook 端，把当前会话状态写进状态文件
install_hooks.py	装/卸 hooks，生成启动器
test_hook.py	行为测试，python test_hook.py 直接跑

状态目录：~/.claude/cc-light/

• sessions/<session_id>.json —— 每个会话一个，原子写入
• window.json —— 窗口位置和大小

事件映射

Claude Code 事件	状态	异步
SessionStart	绿
UserPromptSubmit	黄
PreToolUse / PostToolUse	黄	✓
PermissionRequest	红
Elicitation（Claude 提问）	红
Notification	红（软）
PermissionDenied / ElicitationResult	黄	✓
Stop	绿
SessionEnd	删除记录	✓

许可证

MIT © hasong66