English: English version
Beacon 是 Claude Code 的环境状态挂件：在 Windows 上常驻置顶的 三色信号灯, 把所有并发的 Claude Code 会话(跨仓库、跨 agent)归纳为一句话——是否有会话 在等你、是否有会话在你没盯着的时候悄悄在后台完成了、还是都仍在跑——不需要 逐个会话去看列表。
| 灯 | 状态 | 含义 |
|---|---|---|
| 🔴 红 | waiting |
需要你——回合已结束且没有任何任务在跑,或触发了权限/输入提示 |
| 🟡 黄 | bg_done |
某个后台子任务在你已经不再盯着这个回合之后完成了 |
| 🟢 绿 | working |
忙碌中——主回合正在进行,或仍有子任务在后台运行 |
完整状态机与渲染规则见 docs/lamp-semantics.md。
最简单、也是大多数人想要的方式:Claude Code 和挂件在同一台 Windows 机器
上,不需要从另一台机器查看,完全不跑 beacon-serve。三步:
# 1. 构建挂件(Windows exe,通过 Docker 构建——本机不需要装 .NET)
cd /path/to/beacon
./build-widget.sh
# 2. 把 hook 接入 Claude Code 的 settings.json(WSL 或 原生 Windows 均可——
# 具体粘贴的代码块见 docs/install.md,也可以用可选的安装脚本)
# 3. 运行挂件(config.json 里 sources 保持默认的 [] 空列表——这就是 file
# 模式,挂件直接读本地的 sessions 目录,无需 HTTP / token / beacon-serve)
& "C:\path\to\beacon\windows\beacon-widget\publish\beacon-widget.exe"
# 3b.(可选)改为正式安装——把 exe 拷贝到稳定的每用户目录,创建开始菜单 +
# 开机自启动快捷方式:
& "C:\path\to\beacon\windows\beacon-widget\publish\beacon-widget.exe" --install不论 Claude Code 跑在 WSL 里还是原生 Windows 上,Beacon 都能用;挂件本身
始终跑在 Windows 上。两种拓扑的完整安装步骤、前置条件、卸载方式和手动测试
见 docs/install.md。
如果你想从另一台机器查看会话(挂件跑在与 Claude Code 不同的主机上),
那就是 serve 模式:每台生产者主机跑一个 beacon-serve,挂件的
sources 里填 {url, token}。这是可选的进阶路径,单机用户用不到——见
docs/install.md"生产者安装"和
docs/deploy-runbook.md(两种模式的从零部署 +
自检手册,从"模式决策树"开始)。
| 文档 | 内容 |
|---|---|
docs/lamp-semantics.md |
权威规范——三色灯模型、hook 端的每会话状态机、挂件渲染(浮窗/托盘/双模式、托盘样式、背景透明度、边框、灭灯样式、固定到所有虚拟桌面)、灯效(绿脉冲/进入脉冲/红久拖升级/空闲心跳)、挂件边框健康度(source 可达性、degraded/blackout、与空闲心跳的耦合)、完整示例 |
docs/config.md |
config.json 全量配置项参考(JSONC 支持、首次运行模板、窗口位置记忆) |
docs/install.md |
两种主机拓扑、前置条件、两种拓扑各自的安装/卸载(手动 + 安装脚本)、挂件构建、手动测试、仓库目录结构 |
docs/event-schema.md |
每会话 JSON 契约、hook 消费的 7 个 Claude Code 事件、toast 通知、两个 hook 变体(bash / PowerShell)的对等关系 |
docs/architecture-v2.md |
v2——多主机、多 agent 工具的下一版架构。Phase 1(beacon-serve + adapter 本地写入 + 挂件多 sources)和 Phase 2(beacon-serve 绑定 0.0.0.0 + 挂件并发轮询/超时降级/per-source 启用禁用,含 2026-07 wrap-up 的 adapters/ 分层 + 安装脚本拆分)均已实现,v2-wrapup 分支,尚未合并/上线;不再用"Phase N"编号,往后是一份开放的未来候选项清单。 adapter + beacon-serve + 多源挂件、协议扩展(source/host)、可达性、阶段进展 |
docs/serve.md |
v2 Phase 1/2(已实现,v2-wrapup 分支)。 beacon-serve——只读 HTTP 服务参考:端点、鉴权、绑定(已安装服务默认 0.0.0.0)、CLI/环境变量、如何接入挂件的 sources |
docs/deploy-runbook.md |
2026-07 wrap-up。 面向零先验上下文 AI agent 的部署手册——决策树、精确的部署命令顺序、自我验证清单、按拓扑给出的可达性提示 |
- 两个独立部件,一份契约。 hook 和挂件从不直接互相调用——它们只约定
好每会话 JSON 文件的字段形状。详见
docs/event-schema.md。 - 三种状态而非两种(
working/waiting/bg_done),这样当你不在场时 某个子任务完成会点亮黄灯,而不是误报成红灯。详见docs/lamp-semantics.md。 - hook 绝不抛错。 每一次写文件、每一次子进程调用都被包裹起来,失败时 静默处理——hook 始终以退出码 0 结束,绝不阻塞或打断 Claude Code 的一个 回合。
- 编译型 C# WPF 挂件,在 Docker 里构建。 构建和运行都不依赖本机安装
.NET;带单实例保护;声明 Per-Monitor-V2 高 DPI 感知。详见
docs/install.md。 - 安装以手动为先。 直接粘贴进
settings.json的代码块是主要路径; 合并式安装脚本只是可选的便利工具,且从不做静默改动。详见docs/install.md。 - 挂件自装(
--install/--uninstall)。 一步式拷贝到稳定的每用户目录、 写好配置模板、创建开始菜单 + 开机自启动快捷方式,无需管理员权限,不碰 防火墙/网络。详见docs/install.md"挂件自装"。