Agent Status Light

Local hardware for coding agents

Physical status for agent work.

Agent hooks enter the desktop runtime. The desktop app verifies firmware and mirrors state to an ESP32 red / yellow / green signal light.

Download desktop app Official firmware service Read hardware guide

给 coding agent 用的本地硬件

把 agent 状态变成桌面旁边的物理信号灯。

Agent hooks 进入桌面 app，本地 runtime 校验固件并把状态同步到 ESP32 红黄绿信号灯。

下载桌面 app 官方固件更新服务 阅读硬件指南
Waiting等待确认

User confirmation is needed.需要用户确认时亮起。

red solid红色常亮
Thinking / Running思考中 / 运行中

Planning or tools are active.Agent 正在规划或工具正在执行。

yellow blink黄色闪烁
Idle空闲

The agent is ready.Agent 已就绪时亮起。

green solid绿色常亮
  1. Agent hooksAgent hooks agent-status-light hook
  2. Desktop app桌面 app 127.0.0.1:8765
  3. ESP32 firmwareESP32 固件 agent-status-light-v1
  4. Signal light信号灯 R/Y/G GPIO

Installable app

Direct app downloads use formal Release assets. agent-status-light_darwin-arm64.dmg

Manifest verified

Official updates use entitlement-checked metadata, a merged bin, and matching manifest. merged bin + manifest

Formal versions only

RC/prerelease assets stay out of the public download path.

Hardware kit

Coming soon. Purchase links are not live yet.

可安装桌面 app

直接下载只使用正式 Release assets。 agent-status-light_darwin-arm64.dmg

Manifest 校验

官方更新使用权益校验后的 metadata、merged bin 和匹配 manifest。 merged bin + manifest

仅正式版

RC/prerelease 不进入普通用户稳定下载路径。

硬件套件

即将开放，不伪造购买链接。
Default signal states默认信号状态

Default signal states默认信号状态

Idle空闲

Green solid when the agent is ready.绿色常亮，表示 agent 已就绪。

idle
Thinking思考中

Yellow blink while the agent is planning.黄色闪烁，表示 agent 正在规划。

thinking
Running运行中

Yellow blink while tools are active.黄色闪烁，表示工具正在执行。

running
Waiting等待确认

Red solid when user confirmation is needed.红色常亮，表示需要用户确认。

waiting

Download desktop app

Download desktop app

Install the desktop app from GitHub Releases. The app owns local state, agent hooks, device setup, and firmware flashing.

Direct downloads

macOS agent-status-light_darwin-arm64.dmg Windows agent-status-light_windows-amd64_setup.exe Linux agent-status-light_linux-amd64.tar.gz
View release notes Download checksums
  • macOS agent-status-light_<version>_darwin-arm64.dmg
  • Windows agent-status-light_<version>_windows-amd64_setup.exe
  • Linux agent-status-light_<version>_linux-amd64.tar.gz

Checksums are published with release assets.

下载桌面 app

下载桌面 app

从 GitHub Releases 安装桌面 app。它负责本地状态、agent hooks、设备设置和固件刷写。

直接下载

macOS agent-status-light_darwin-arm64.dmg Windows agent-status-light_windows-amd64_setup.exe Linux agent-status-light_linux-amd64.tar.gz
查看发布说明 下载 checksums
  • macOS agent-status-light_<version>_darwin-arm64.dmg
  • Windows agent-status-light_<version>_windows-amd64_setup.exe
  • Linux agent-status-light_<version>_linux-amd64.tar.gz

Release assets 会同时发布 checksums。

Official firmware service

Official firmware service

Sign in through the desktop app and activate the connected device to receive official firmware metadata and short-lived download tokens. Final users do not need Arduino IDE, arduino-cli, PlatformIO, ESP-IDF, or esptool.

Service delivery

  1. Sign in through the desktop app signin
  2. Activate the connected device activate
  3. Use a short-lived token for official firmware assets token
  • Merged bin agent-status-light-esp32-wroom32-v<version>-merged.bin
  • Manifest agent-status-light-esp32-wroom32-v<version>-manifest.json

The desktop app checks entitlement, manifest metadata, size, SHA-256, chip, format, and flash offset before flashing.

Firmware guide

官方固件更新服务

官方固件更新服务

通过桌面 app 登录并激活当前设备后，桌面 app 会获取官方固件 metadata 和短期 download token。最终用户不需要 Arduino IDE、arduino-cli、PlatformIO、ESP-IDF 或 esptool。

服务交付路径

  1. 通过桌面 app 登录 signin
  2. 激活当前连接的设备 activate
  3. 使用短期 token 获取官方固件资产 token
  • Merged bin agent-status-light-esp32-wroom32-v<version>-merged.bin
  • Manifest agent-status-light-esp32-wroom32-v<version>-manifest.json

桌面 app 会在刷写前检查权益、manifest 元数据、大小、SHA-256、芯片、格式和刷写偏移。

固件指南

Account + activation + device binding

Activation and official service rights

Open source stays open. Official firmware updates, one-click flashing, and future remote services use account login, an activation code, and the bound device fingerprint.

This is not DRM. The device fingerprint is a service binding identifier, not strong proof that hardware came from us.

  1. 1 Sign in

    Use GitHub OAuth or an email magic link in the desktop app.

    account
  2. 2 Redeem activation code

    A purchased hardware kit or service grant includes a one-time activation code.

    activation-code
  3. 3 Bind one device

    One code binds one account and one device; the same account and device can redeem again idempotently.

    device-binding
  4. 4 Receive official updates

    The desktop app requests entitlement-checked metadata and short-lived firmware download tokens.

    official-updates

Privacy and storage boundary

  • Activation codes, sessions, magic links, OAuth state, and download tokens are stored as hashes, not plaintext.
  • Full MAC addresses are not shown; UI uses a short fingerprint and the service stores hashed device identity.
  • Audit events use stable reason codes and ids, not secrets.
  • Unactivated or offline devices keep local basic status-light features.

账号 + 激活码 + 设备绑定

激活与官方服务权益

源码仍可自行构建。官方固件更新、一键刷写和未来远程服务使用账号登录、激活码和已绑定设备指纹。

这不是不可绕过的 DRM。设备指纹只是服务绑定标识，不是硬件一定出自我们的强证明。

  1. 1 登录账号

    在桌面 app 中使用 GitHub OAuth 或邮箱 magic link。

    account
  2. 2 兑换激活码

    购买硬件套件或服务权益后会获得一次性激活码。

    activation-code
  3. 3 绑定一台设备

    一码绑定一个账号和一台设备；同账号同设备重复兑换会幂等成功。

    device-binding
  4. 4 获取官方更新

    桌面 app 请求权益校验后的 metadata 和短期固件 download token。

    official-updates

隐私与存储边界

  • 激活码、session、magic link、OAuth state 和 download token 只存 hash，不存明文。
  • 界面不显示完整 MAC；UI 使用短指纹，服务端存储 hash 后的设备身份。
  • Audit events 只记录稳定 reason code 和 id，不记录 secret。
  • 未激活或离线设备仍保留本地基础状态灯功能。

Setup path

Setup path

  1. 1 Install app

    Open the desktop app directly after installing the package for your OS.

  2. 2 Flash firmware

    Choose the manifest or matching firmware image in the desktop app and confirm the preview.

  3. 3 Sync agents

    Use supported hook integrations so coding agent state reaches the local runtime.

设置路径

设置路径

  1. 1 安装 app

    安装对应系统的包后，直接打开桌面 app。

  2. 2 刷写固件

    在桌面 app 中选择 manifest 或匹配的固件文件，检查预览后确认。

  3. 3 同步 agent

    使用支持的 hook 集成，让 coding agent 状态进入本地 runtime。

Coming soon

Hardware kit

A ready-to-use kit is planned, but purchase links are not live yet.

Coming soon

即将开放

硬件套件

计划提供可直接使用的套件，但购买链接尚未开放。

即将开放

Debugging and documentation

Debugging and documentation

Keep the normal path short. Use these documents when you need wiring, firmware, hook, or release details.

Hardware guide docs/hardware.md Firmware guide docs/firmware.md Desktop app docs/desktop.md Release process docs/release.md Hook setup docs/hooks.md GitHub masiqi/agent-status-light

调试与文档

调试与文档

普通路径保持简短；需要接线、固件、hook 或发布细节时再进入这些文档。

硬件指南 docs/hardware.md 固件指南 docs/firmware.md 桌面 app docs/desktop.md 发布流程 docs/release.md Hook 设置 docs/hooks.md GitHub masiqi/agent-status-light

When something does not light up

When something does not light up

  • Check USB or Bluetooth serial selection in the desktop app.
  • Reset the ESP32, then run firmware status and Devices Test.
  • If status is verified but colors are wrong, inspect GPIO mapping, channel order, and polarity.

如果灯没有按预期亮起

如果灯没有按预期亮起

  • 先在桌面 app 中检查 USB 或蓝牙串口选择。
  • 重置 ESP32，然后运行 firmware status 和 Devices Test。
  • 如果状态已验证但颜色不对，检查 GPIO mapping、通道顺序和极性。