Light · 桌面状态胶囊

屏幕顶部常驻的悬浮胶囊，实时展示 Claude Code 与 Codex CLI 的工作状态。磨砂玻璃质感，余光一瞥就知道 AI 在干活、做完了还是出错了，不用切窗口。

详细的产品设计见 PRD.md。

功能

状态一目了然：工作中泛蓝光呼吸、完成变绿打勾、出错变红，还显示当前工具与用时。
多会话 / 多 agent：Claude Code 与 Codex 同时跑也能分栏显示，互不打架。
一键接入：app 内一键把 hooks 写进 Claude Code / Codex 配置，无需手写 JSON（安全合并、不覆盖、自动备份）。
顺手的小工具：桌面备忘录、当前播放的音乐（可上一首 / 下一首 / 暂停）。
磨砂玻璃 UI：任何壁纸下都清晰；鼠标移上去展开详情面板。
纯本地：只监听 127.0.0.1，不联网、不上传任何数据。

下载安装（Windows）

去 Releases 下载 Light-Setup-x.y.z.exe，双击安装即可（按当前用户安装，免管理员、不弹 UAC）。

想自己从源码打包安装包？见 installer/README.md。

截图（示意）

       ╭──────────────────────────────────╮
       │  ● Claude  Edit  │  ● Codex  idle │
       ╰──────────────────────────────────╯
              hover → 展开当前任务摘要
              click → 展开事件流面板

● 灰：idle
● 蓝（呼吸光晕）：working
● 绿（勾选动画）：done
● 红（抖动）：error

快速开始

依赖：Node 18+、Windows / macOS / Linux。

# 1. 装依赖（首次约 5 分钟，Electron 30.5.1 会优先用本地缓存）
npm install

# 2. 启动开发模式（Vite + Electron）
npm run dev

启动成功后，你的屏幕顶部中央会出现一个深色的胶囊条。把鼠标移上去会展开摘要，点击会展开事件面板。

验证一下没装 hook 时也能看到效果

打开一个新终端，发个测试事件：

# Windows PowerShell
Invoke-RestMethod -Uri http://127.0.0.1:51789/event -Method POST -ContentType 'application/json' -Body (@{
  agent = 'claude-code'
  type = 'user_prompt'
  message = 'Refactor the auth middleware'
} | ConvertTo-Json)

# macOS / Linux
curl -X POST http://127.0.0.1:51789/event \
  -H "Content-Type: application/json" \
  -d '{"agent":"claude-code","type":"user_prompt","message":"Refactor the auth middleware"}'

胶囊会切换到蓝色 "working" 状态。再发 {"agent":"claude-code","type":"stop"} 会变绿，8 秒后回灰。

接入 Claude Code / Codex

最简单的方式（推荐）： 打开 Light，鼠标移到胶囊上展开面板 → 「接入 Agent」 一栏点 「一键接入」；或右键托盘图标 → 「一键接入 Claude / Codex」。它会把 hooks 安全合并进 ~/.claude/settings.json 和 ~/.codex/hooks.json（保留你已有的配置，不覆盖，并先写一份 .light-backup），路径自动填好。接入后重启对应的 Claude Code / Codex 即可生效。

下面是手动配置的方式（不想用一键时）。完整说明见 hooks/README.md。

把以下内容合并到你的 ~/.claude/settings.json，并把 <LIGHT_DIR> 换成你本机 light 的绝对路径（Windows 上用正斜杠 / 即可，例如 C:/Users/你的用户名/AppData/Local/Programs/Light）：

{
  "hooks": {
    "SessionStart":    [{ "hooks": [{ "type": "command", "command": "node <LIGHT_DIR>/hooks/claude-hook.mjs session_start" }] }],
    "SessionEnd":      [{ "hooks": [{ "type": "command", "command": "node <LIGHT_DIR>/hooks/claude-hook.mjs session_end" }] }],
    "UserPromptSubmit":[{ "hooks": [{ "type": "command", "command": "node <LIGHT_DIR>/hooks/claude-hook.mjs user_prompt" }] }],
    "PreToolUse":      [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node <LIGHT_DIR>/hooks/claude-hook.mjs tool_use" }] }],
    "Stop":            [{ "hooks": [{ "type": "command", "command": "node <LIGHT_DIR>/hooks/claude-hook.mjs stop" }] }]
  }
}

改完后彻底重启 Claude Code 进程才会生效。详见 hooks/README.md。

Codex CLI 同理：把下面内容写进 ~/.codex/hooks.json（事件格式与 Claude 一致），模板见 hooks/codex-hooks.example.json：

{
  "hooks": {
    "SessionStart":     [{ "matcher": "startup|resume|clear|compact", "hooks": [{ "type": "command", "command": "node \"<LIGHT_DIR>/hooks/codex-hook.mjs\" session_start" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "node \"<LIGHT_DIR>/hooks/codex-hook.mjs\" user_prompt" }] }],
    "PreToolUse":       [{ "matcher": "*", "hooks": [{ "type": "command", "command": "node \"<LIGHT_DIR>/hooks/codex-hook.mjs\" tool_use" }] }],
    "Stop":             [{ "hooks": [{ "type": "command", "command": "node \"<LIGHT_DIR>/hooks/codex-hook.mjs\" stop" }] }]
  }
}

老版本 Codex 没有 hooks，可改用 hooks/codex-wrap.cmd 包装调用兜底（详见 hooks 文档）。

目录结构

light/
├── PRD.md                 # 产品需求文档
├── package.json
├── tsconfig.json          # 渲染层 TS 配置
├── tsconfig.electron.json # 主进程 TS 配置
├── vite.config.ts
├── index.html
├── scripts/
│   └── dev.mjs            # 开发启动脚本（先 Vite 后 Electron）
├── electron/              # 主进程（Node）
│   ├── main.ts            # 入口：窗口 / 托盘 / IPC
│   ├── preload.ts         # 安全 bridge
│   ├── server.ts          # 本地 HTTP 服务
│   ├── state.ts           # 事件状态机
│   └── hooks-setup.ts     # 一键接入：安全合并 hooks 到 Claude/Codex 配置
├── src/                   # 渲染层（React + Framer Motion）
│   ├── App.tsx
│   ├── main.tsx
│   ├── styles.css
│   ├── types.ts
│   ├── hooks/useLightEvents.ts
│   └── components/
│       ├── Island.tsx
│       ├── AgentPill.tsx
│       └── ExpandPanel.tsx
└── hooks/                      # 注入 Claude Code / Codex 的脚本
    ├── claude-hook.mjs         # Claude Node 适配器
    ├── claude-hook.cmd         # Windows 入口
    ├── claude-hook.sh          # Unix 入口
    ├── codex-hook.mjs          # Codex 官方 hooks 适配器
    ├── codex-hook.cmd          # Windows 入口
    ├── codex-hook.sh           # Unix 入口
    ├── codex-wrap.mjs          # Codex 旧版包装（无 hooks 时回退）
    ├── codex-wrap.cmd          # Windows 入口
    ├── settings.example.json   # Claude ~/.claude/settings.json 模板
    ├── codex-hooks.example.json # Codex ~/.codex/hooks.json 模板
    └── README.md

HTTP API

POST http://127.0.0.1:51789/event

{
  "agent": "claude-code" | "codex",
  "type": "session_start" | "user_prompt" | "tool_use" | "stop" | "notification" | "error",
  "sessionId": "可选",
  "tool": "可选，PreToolUse 时填工具名",
  "message": "可选，文本摘要",
  "timestamp": "可选，ISO8601"
}

GET /health 健康检查；GET /state 拿当前状态（调试用）。

隐私与安全

纯本地运行：HTTP 服务只绑定 127.0.0.1，不监听公网，外部机器无法访问。
不联网、不收集数据：没有任何遥测 / 上报；备忘录只存在本机 %AppData%\light\memos.json。
渲染层隔离：contextIsolation: true、nodeIntegration: false，页面拿不到 Node 能力。
不执行任意命令：/event 只接收字符串字段用于显示，服务端不会据此执行 shell；媒体控制只接受固定的枚举动作。
本地端口 51789 无鉴权（按设计——只有本机程序能访问）。如果你介意同机其他程序往里发"假状态"，可自行加 token 校验。

状态机

事件	状态变化
`session_start`	→ `idle`，清空 currentTool
`user_prompt`	→ `working`，记录 startedAt 与 lastPrompt
`tool_use`	→ `working`，更新 currentTool
`stop`	→ `done`，8 秒后自动转 `idle`
`error`	→ `error`，5 秒后自动转 `idle`
`notification`	不改状态，只入事件流

路线图

v1（当前）：状态展示、双 agent、hover/click 展开、事件流。 v2：通知聚合（微信 / 邮件 / Slack / GitHub）、打包发布、多屏支持。

已知限制

Codex 通过官方 hooks 接入（事件级上报，与 Claude 一致）；但 Codex 没有 SessionEnd 事件，无法像 Claude 那样关窗即消失，因此 Light 在 Codex 安静约 15 秒后自动收起它的胶囊（下次有事件会再出现）。老版本 Codex 无 hooks，只能用包装脚本拿到 start / stop。
仅在 Windows 11 上做过完整验证，macOS / Linux 的透明窗口表现可能有差异。
安装包通过 npm run dist + Inno Setup 生成（见 installer/README.md）。

许可

MIT

Navigation Menu

Repository navigation

About

Repository files navigation

Light · 桌面状态胶囊

功能

下载安装（Windows）

截图（示意）

快速开始

验证一下没装 hook 时也能看到效果

接入 Claude Code / Codex

目录结构

HTTP API

隐私与安全

状态机

路线图

已知限制

许可

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
bridge		bridge
electron		electron
hooks		hooks
installer		installer
scripts		scripts
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
PRD.md		PRD.md
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
tsconfig.electron.json		tsconfig.electron.json
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

Latest commit

History

Folders and files

Repository files navigation

Light · 桌面状态胶囊

功能

下载安装（Windows）

截图（示意）

快速开始

验证一下没装 hook 时也能看到效果

接入 Claude Code / Codex

目录结构

HTTP API

隐私与安全

状态机

路线图

已知限制

许可

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages