Claude Eyes：给你的 Claude Code 装上红绿灯，实时监控每个窗口状态

GitHub：https://github.com/wzp0514/claude-eyes　|　Gitee：https://gitee.com/wzp0514/claude-eyes

这是什么

Claude Code 用久了，窗口开得越多越容易懵——哪个在干活？哪个在等确认？哪个崩了？

Claude Eyes 是一个跨平台悬浮指示灯面板，用四色圆点实时告诉你每个 Claude Code 窗口的运行状态。开窗亮灯、关窗灭灯，直观得像红绿灯。

核心能力：

• 🟢 绿灯常亮 — Claude 正在工作
• 🟡 黄灯闪烁 — 等待你确认（权限请求）
• ⚪ 灰灯常亮 — 空闲中
• 🔴 红灯闪烁 — 出错了

多窗口同时监控，每个窗口一个灯，全部聚合在一个面板里，置顶悬浮，不怕被其他窗口挡住。

---

安装

第一步：检查 Python

打开终端，确认 Python 已安装：

python --version   # 需要 3.9 或更高版本

如果没装：

• Windows：去 python.org 下载，安装时勾选"Add Python to PATH"
• macOS：brew install python3
• Linux：sudo apt install python3 python3-pip python3-tk

第二步：安装并初始化

# 一条命令：安装 + 自动配置 Hook（二选一）
pip install git+https://github.com/wzp0514/claude-eyes.git && python -m claude_eyes.setup

# 国内用 Gitee 更快
pip install git+https://gitee.com/wzp0514/claude-eyes.git && python -m claude_eyes.setup

没装 git？去项目页下载 ZIP，解压后：

cd claude-eyes-main && pip install . && python -m claude_eyes.setup

第三步：验证

python -m claude_eyes.demo

面板应出现在屏幕右下角，显示 4 个彩色圆点。

重启 Claude Code，面板出现在右下角。发条消息，对应的灯就会亮起来。

---

使用指南

面板交互

面板始终置顶悬浮，可以直接拖拽到任意位置。

右键菜单

在面板上右键点击，弹出功能菜单：

选项	说明
切换为横排 / 切换为竖排	竖排显示时间戳 + 项目名，横排只显示灯
切换为上旧下新 / 切换为上新下旧	调整排序方向，默认新会话在上
面板位置	选择固定到屏幕四角之一
显示全名 / 截断名称	项目名称太长时切换显示方式
演示模式	一键添加各种状态的演示灯
关闭 <项目名>	关闭指定窗口的灯
全部关闭	清除所有灯

演示模式

没有真实会话也能预览所有状态。右键 → 演示模式，选择任意颜色；或命令行：

python -m claude_eyes.demo          # 一次性展示全部 4 种状态
python -m claude_eyes.demo clear    # 清除所有演示灯

状态含义

每个灯显示两个时间戳：你说话时间 | Claude 完成时间，用 | 分割。

灯色	含义	触发时机
🟢 绿	工作中	你发消息、Claude 开始/完成执行工具
🟡 黄闪烁	等你确认	Claude 请求权限（写文件、执行命令等）
⚪ 灰	空闲	Claude 回复完成、会话开始
🔴 红闪烁	出错	工具执行失败
灯消失	窗口已关	关闭 Claude Code 窗口

---

常见问题

Hook 被误删了怎么办？

不用管。每次 Claude Code 启动（SessionStart）时会自动检查 hooks 是否完整，缺失了会自动补回来。

面板不显示？

1. 确认 hook 已注册：运行 python -m claude_eyes.setup，看是否提示已配置
2. 确认面板能启动：运行 python -m claude_eyes.demo，应弹出面板
3. 重启 Claude Code

灯颜色不对/不更新？

面板每 0.2 秒轮询一次状态文件，最多延迟 0.2 秒。如果灯卡住不动，右键 → 全部关闭，然后重启 Claude Code。

卸载

pip uninstall claude-eyes

手动删除 ~/.claude/settings.json 中包含 claude_eyes.hook 的 hook 条目（也可不删，卸载后这些 hook 命令找不到模块会自动跳过）。

---

架构简述

settings.json hooks
       │  (stdin JSON)
       ▼
   hook.py ──► status/{session_id}.json
                     │  (轮询 200ms)
                     ▼
               manager.py ──► panel.py (tkinter)
                                 ├── HH:MM:SS  ●  项目名
                                 └── ...

• hook.py：接收 Claude Code 事件，写入结构化状态文件
• manager.py：守护进程，轮询状态文件，驱动面板更新
• panel.py：tkinter 悬浮面板，渲染指示灯

零外部依赖，Python 标准库 + tkinter 即可运行。

性能：CPU 占用极低（事件驱动轮询，非忙等），内存约 10 MB，hook 进程 <50ms 即退出，对 Claude Code 自身零影响，全天后台运行无感。

---

链接

• GitHub：https://github.com/wzp0514/claude-eyes
• Gitee：https://gitee.com/wzp0514/claude-eyes
• 问题反馈：Issues