Clawdmeter – 一个桌面版 Claude Code 使用情况仪表盘

它是什么 – 一个基于 ESP‑32 的小型设备，放在你的桌面上，显示你已使用的 Claude Code 配额比例。它与 Claude Code API 通信，获取当前会话和每周的使用数据，并在小型彩色 OLED 屏幕上显示。该设备还充当蓝牙 HID 键盘，通过两个侧边按钮触发 Claude Code 的语音模式（空格键）和模式切换（Shift + Tab）。

工作原理（概览）

你电脑上的守护进程 – 一个小型 Python 程序在后台运行（macOS 上为 LaunchAgent，Linux 上为 system‑d 用户服务，Windows 上为托盘应用）。它读取你的 Claude Code OAuth 令牌，发起一次低成本的 API 请求，并从响应头中提取使用率百分比。
BLE 传输 – 守护进程打开与 ESP‑32 的 BLE 连接，并将一段简短的 JSON 负载（会话 %/重置时间，每周 %/重置时间，状态）写入自定义 GATT 特性。
固件 – ESP‑32 固件（使用 PlatformIO 和 LVGL 构建）接收 JSON 数据，更新屏幕上的仪表盘，并动画化一个名为“Clawd”的吉祥物，其活跃程度反映你当前的使用速率。
物理控制 – 两个侧边按钮直接向主机发送 BLE‑HID 键盘事件（空格键和 Shift + Tab），让你无需触碰键盘即可启动语音模式或切换 Claude Code 模式。

快速上手

平台	步骤（概要）
macOS	1. 运行 `./flash-mac.sh <board>` 上传固件。2. 在系统设置 → 蓝牙中配对设备。3. 运行 `./install-mac.sh` – 创建 Python 虚拟环境，安装 `bleak`/`httpx`，并注册一个每 60 秒轮询一次使用情况的 LaunchAgent。
Linux	使用相同的刷写脚本（`./flash.sh`）。通过 `bluetoothctl` 配对。使用 `./install.sh` 安装守护进程，并通过 `systemctl --user start claude-usage-daemon` 启动。
Windows	使用 PlatformIO 刷写（`pio run -d firmware -e <board> -t upload`）。通过设置 → 蓝牙配对。运行 `install-windows.ps1` – 创建虚拟环境，安装依赖项，注册用户级自动启动项，并启动托盘应用。

三个安装脚本均会设置一个包含所需 Python 库（bleak 用于 BLE，httpx 用于 API 调用，Windows 上还有 UI 辅助工具）的虚拟环境。守护进程会将日志写入文件（或 macOS LaunchAgent 日志），便于排查问题。

核心功能

实时使用率仪表 – 以简单的条形图显示当前会话使用率和每周使用率。
动画启动画面 – 像素艺术“Clawd”吉祥物的动画速度随使用率上升而加快；你可以通过中间按钮切换动画。
BLE‑HID 快捷键 – 一个按钮发送空格键（Claude Code 语音模式的按下说话），另一个按钮发送 Shift + Tab（模式切换）。
硬件无关的固件 – 核心 UI 代码位于 firmware/src/；板卡特定的 HAL 文件位于 firmware/src/boards/。添加新的 ESP‑32 板卡只需新建一个文件夹和一个 PlatformIO 环境即可。
桌面模拟器 – 构建 sim 环境可在你的 PC 上通过 SDL2 窗口运行 UI，便于在不刷写硬件的情况下调整界面。
开源资源 – 转换脚本可将 Anthropic 官方的“Clawd”精灵图和 Lucide 图标转换为 LVGL 兼容的 C 数组。

哪些人可能会需要它？

Claude Code 高级用户，拥有订阅并希望快速获得配额使用情况的视觉提示。
硬件爱好者，寻找 ESP‑32 上使用 BLE‑HID + 自定义 GATT 服务的完整示例。
开发者，对一个小型、端到端项目感兴趣，该项目将云 API、Python 守护进程和嵌入式固件整合在一起。

注意事项与许可

仓库包含 Anthropic 的专有吉祥物图形和品牌字体。虽然代码本身开源，但资源未获自由许可，因此再分发可能受限。
守护进程每分钟发起一次最小 API 调用（一次 Haiku 的令牌），基本免费，但仍计入你的 Claude Code 配额。
必须进行 BLE 配对；该设备不会扫描任意外设 – 它仅与已配对的主机通信。

简而言之： Clawdmeter 是一个即插即用的桌面小工具，可可视化 Claude Code 使用情况并提供快捷键，基于 ESP‑32 硬件、BLE 和轻量级 Python 守护进程构建。它是一个真实、可用的项目，处于 AI 服务监控与嵌入式 UI 设计的交汇点。

HermannBjorgvin/Clawdmeter