convez.ai
AgenteDevOps & InfraestruturaIntermediário
MrHulu

AgentLamp — Tela de Status para AI Agents

MrHulu/agentlamp

Tela de status físico para AI agents — uma piscada de olhos para saber o que está acontecendo

Ver no GitHub
BomPluginScore · de 0 a 100

Uma tela física de status para agentes de codificação IA (Claude Code, Codex) que roda em uma placa ESP32 de ~$15 ou no iPhone. Mostra em tempo real se o agent está codificando, pensando, aguardando input ou em erro — sem precisar alternar janelas ou revisar logs.

Instalação

$npx convez-ai MrHulu/agentlamp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
5
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Monitorar tarefas longas do Claude Code sem interrupção de fluxo
  • Gerenciar múltiplos agents/máquinas em paralelo com agregação visual
  • Ambiente autoexplicativo que comunica estado (codificando, aguardando, erro, concluído) com cores e indicadores

Veredito

Ferramenta niche mas bem executada: transforma monitoramento passivo de agents em design ambiental. Privacidade por padrão (default-deny), suporta modo local e nuvem, código limpo e bem documentado. Ideal para quem trabalha com AI agents longos e quer eliminar context switching.

README

A tradução para o português deste README ainda está na fila.

简体中文 · English

AgentLamp

让你的 AI 编程助手,从此看得见。

抬眼一瞥就知道 Claude Code / Codex 在写代码、在思考、在等你拍板,还是报错了—— 不切窗口、不盯日志。一块桌上的小屏,或你口袋里的 iPhone,安静地亮着。

readers license privacy tests self-host stars


你起身接了杯水。回来盯着屏幕——Claude Code 是卡住了,还是十分钟前就跑完、正等着你点下一步? 于是你又一次 Cmd-Tab 翻窗口、翻日志,心流断在半路上。

AgentLamp 把这件事变成一抬眼的事。 一块约 $15 的小屏立在桌角——或者,就用你手里的 iPhone——agent 在干什么,一眼就知道。

单会话聚焦多 agent 舰队额度告警需要你处理
谁在 CODING几台机器 / 几个 agent 在忙5 小时 / 每周额度WAITING / ERROR 闪红提醒

同一块屏,会随状态变色——紫色在写、黄色等你、红色报错、绿色完成。完整 12 种状态见下方设计板。

📱 没有板子?你的 iPhone 就是一块 AgentLamp

🆕 5 分钟、零硬件——先把整套 AgentLamp 跑在你手机上。 不想买板子、不想焊接、不想刷固件?任何 iPhone(iOS 16+)粘一个单文件脚本,就是一块实时的读取端。下图就是它此刻跑在真机主屏上的样子:

装一个免费的 Scriptable、粘贴一个单文件脚本、填 3 个常量——5 分钟,你的主屏 / 锁屏上就有一块实时的 AgentLamp 组件。无需 App 内购、无需越狱、无需开发者账号。

  • 零硬件、零成本:手头的 iPhone 就够,先用它把整套流程跑通,再决定要不要上实体灯。
  • 跨机器聚合:手机读的是所有电脑汇总后的一块帧——几台机器在忙、谁在 focus,一个组件全看到。
  • 永不空白:网络抖一下也不会白屏,它缓存上一帧并标记离线,恢复后自动刷新。
  • 同一套隐私红线:只读、token 只走 Authorization 头、丢手机可即时吊销(下次刷新立刻变 PAIRING REQUIRED,绝不继续显示缓存)。
  • 想要秒级提醒? 附带一个可选的 P2 告警脚本,WAITING / ERROR 经 Pushcut 推到锁屏。

iOS 把组件刷新限制在 ~5–15 分钟(系统说了算),天生适合"环境感知"那一瞥;要即时 ping 就加 P2 告警脚本。 当前状态:单文件组件已实现 + 跨语言一致性测试通过,已在真机主屏运行(见上图)。

5 分钟手机端走查 → readers/iphone-widget/DEPLOY.md

✨ 它是什么

AgentLamp 是一个自己动手做的硬件状态屏:一块 Waveshare ESP32-S3 小屏(172×320 + RGB 灯), 实时显示你电脑上 AI 编程助手(Claude Code / Codex)的状态——在写代码、在思考、在等你确认、 报错了、额度快用完了……抬眼一瞥就知道,不打断心流。

它作为**「把硬件接到 AI-agent 状态」的开源教学示例**:一台笔记本 + 一块约 $15 的板子,就能先在本地跑起来,再谈云端。v1 是单人自托管——没有共享、没有多租户、没有你的数据上别人服务器这回事。

🤔 为什么你会想要一个

  • AI 助手在后台跑长任务时,你很容易失去感知:它卡住了?在等你拍板?还是早就跑完了?于是你不停切窗口、盯日志,心流被反复打断。
  • 多台电脑 / 多个会话并行时更乱——到底几个在忙、忙什么?一块屏帮你一次看全。
  • 一块抬眼可见的环境屏(像 Tidbyt 那类信息屏),把「它现在怎样」从一次次主动查询,变成余光里的一瞥。
  • 隐私优先不是口号:默认拒绝(default-deny)脱敏——密钥 / cookie / 原始 prompt / 源码 / 完整路径 / 真实模型名 / 套餐档位,一律不出本机。

🛠 它怎么工作

flowchart LR
  C["采集器(每台电脑一个)<br/>Claude / Codex 钩子 → 本机脱敏"]
  R["Cloudflare Worker + Durable Object<br/>校验 · 聚合 · 出帧"]
  D["ESP32 状态屏<br/>轮询固定地址"]
  C -->|"HMAC 签名 · 仅脱敏摘要"| R
  R -->|"HTTPS"| D
  C -.->|"本地模式:直连局域网"| D

两种模式,先简单后强大:

  • 本地模式(默认,无需云):采集器在局域网提供一个紧凑 JSON 帧,ESP32 直接轮询。无域名、无公网 TLS、无云账号——插上电就能看。
  • 云端中继模式(可选):想离开局域网也能看时,采集器把 HMAC 签名的脱敏摘要推到一个 Cloudflare Worker + Durable Object 中继,设备走 HTTPS 轮询同一个固定地址。天然支持多台电脑(每台一行 enroll 命令接入),换电脑 / 换 WiFi 都很快——设备地址永不变。

3 步跑起来(本地模式):

# 1) 装依赖 + 起本地帧服务器(先在浏览器里 http://localhost:8787/preview 看效果)
pip install -e ".[server]"
python -m agentlamp_server

# 2) 编译并刷固件(PlatformIO)
cd firmware && pio run -e waveshare-s3-lcd-147 -t upload

# 3) 设备开机进配网页,填入帧服务器地址 —— 完成

📟 不止一种屏(读取端 / readers)

任何能拉同一份 JSON 帧的设备,都是合法的「读取端」。云端 / 采集器不感知你用的是哪种硬件——加一种新设备永不动核心代码。

读取端硬件渲染状态成本代码
ESP32 实体灯Waveshare ESP32-S3-LCD-1.47B(172×320 + RGB)C++ / PlatformIO✅ 已上线,~4 秒实时约 $15firmware/
iPhone 组件任意 iPhone(iOS 16+)Scriptable JS🆕 单文件脚本就绪零硬件readers/iphone-widget/

两者渲染同一组场景,区别只在渲染语言和形态——它们共享的是线上契约(一份 JSON 帧),而不是渲染代码。完整目录 → readers/。

🎨 一块屏,说清所有状态

每种状态有自己的主强调色与节奏——开机、配对、舰队、聚焦、额度、告警、报错、离线、休眠…… RGB 灯随状态呼吸,余光就能感知。下面是设计板全貌(也是固件渲染的真实依据):

🔒 隐私与安全

这是 AgentLamp 最较真的部分——一块"显示器"不该成为一个泄密点。

  • 默认拒绝脱敏:采集器是唯一做「原始 → 安全」转换的地方,只上报枚举状态 / 用户自定义别名 / 带密钥 HMAC 标签。
  • 云端只校验、不再脱敏(独立的第二道闸):它校验已脱敏输出的形状,绝不在云端重跑转换逻辑(避免两套实现悄悄跑偏)。
  • 永不上传:provider cookie / refresh token、原始 prompt / 对话、源码、完整本地路径、真实模型 id、套餐档位。
  • 签名防重放(HMAC + nonce + 时间窗 + 幂等)、设备只读令牌(散列存储)、丢失设备可即时吊销。

红线:这台设备不是浏览器——它只拉 JSON 帧、本地渲染;不做账号切换、额度规避、请求代理、云端凭证存储。

📦 硬件清单

  • Waveshare ESP32-S3-LCD-1.47B —— 1.47" 圆角 LCD(172×320)+ RGB LED,需带 PSRAM(帧缓冲要用)。
  • 一根能传数据的 USB-C 线(刷机用,别用只充电的)。
  • 屏和灯都在板上,无需手工接线。

🧭 现状

本地模式可用;云端中继已实现并实测上线、端到端验证通过(Cloudflare Worker + Durable Object + KV)。 455 个自动化测试通过(Python 315 + TypeScript 125 + iPhone reader 15),跨语言一致性由生成式 parity 语料锁定。 设计与演进记录见 docs/devlog/。

⭐ 喜欢就留颗 star

AgentLamp 是我下班后捣鼓的个人项目——因为我自己受够了在一堆终端窗口之间反复横跳,想让 agent 的状态"长"在桌上而不是藏在第 7 个标签页里。

  • 觉得这个想法有意思 → 点个 ⭐ 让我知道有人在看,这是继续做下去最实在的动力;
  • 想要一个自己的 → 直接 fork,本地模式一台笔记本就能跑,按 docs/BUILD.md 走;
  • 有想法 / 想加一种新读取端(你的电子墨水屏?智能手表?)→ 欢迎开 issue 或 PR。

📚 深入文档

支持的硬件 / readers · 产品规格 · 架构 · 设备帧 API · 采集器接入 API · 安全模型 · 脱敏策略 · 威胁模型 · 固件契约 · 云端契约

📄 License

MIT © 2026 Hulu(AgentLamp contributors)。 改动 docs/security/ 或任何脱敏 / 鉴权路径的贡献需经安全审查(见 SECURITY.md / CONTRIBUTING.md)。

Ver o original no GitHub

Bom para

Relacionados