TokenBar

TokenBar

随时查看 Claude Code、Codex、Copilot、Windsurf、Cursor、Gemini、Kiro、GLM、Kimi、Amp……（或任意 AI）的使用限额及重置时间，
并在 LED 显示屏上显示，支持 Mac、Windows、Linux、iPhone、Android、Apple Watch 和 Wear OS。

English · Português

网站和 API 文档： https://chaconlucas.github.io/tokenbar/

---

安装

电脑负责收集数据。 手机和手表只会显示电脑通过 Wi-Fi 发送的数据，所以请始终从电脑开始。

	设备	方法
电脑	Mac（macOS 15+）	curl -fsSL https://raw.githubusercontent.com/ChaconLucas/tokenbar/main/scripts/install-mac.sh | sh
	通过 Homebrew 安装 Mac 版	brew install --cask chaconlucas/tokenbar/tokenbar
	Windows 10/11	从 Releases 下载 TokenBar-Windows-setup.exe。SmartScreen 发出警告？选择 更多信息 → 仍要运行
	通过 winget 安装 Windows 版	winget install ChaconLucas.TokenBar（等待 Microsoft 审核）
	Linux	从源代码构建，参见从源代码构建
手机和手表	iPhone（iOS 17+）	在安装了 Xcode 的 Mac 上连接 iPhone：curl -fsSL https://raw.githubusercontent.com/ChaconLucas/tokenbar/main/scripts/install-ios.sh | sh。在 sh 后添加 -s -- --auto，Mac 就会自动续期并更新
	Apple Watch（watchOS 10+）	随 iPhone 应用提供：iPhone → Watch 应用 → TokenBar → 安装
	Android 8+	从 Releases 下载 TokenBar-Android.apk（允许“安装未知应用”）
	Wear OS 3+	从 Releases 下载 TokenBar-WearOS.apk，并使用 adb 安装（步骤）
其他	VS Code	在扩展中搜索 TokenBar（Marketplace，ID 为 chaconlucas.tokenbar）
	Raycast	从源代码运行：cd raycast && npm install && npm run dev（详情）
	Stream Deck	从 Releases 下载 TokenBar-StreamDeck.streamDeckPlugin，然后双击打开（详情）
	插件	Claude Code：claude plugin marketplace add ChaconLucas/tokenbar && claude plugin install tokenbar@tokenbar。Codex 和 Gemini CLI：插件（MCP 服务、/tokenbar、达到 80% 时发出警告）
	CLI + MCP	curl -fsSL https://raw.githubusercontent.com/ChaconLucas/tokenbar/main/scripts/install-cli.sh | sh（Node 18+）。Claude Desktop：从 Releases 下载 TokenBar.mcpb，然后双击打开。Cursor、VS Code、Windsurf、Zed、Gemini、Goose 等：在 AI 中安装（一键安装，或使用 --add-to <tool>）

更新： Mac、Windows 和 Android 可在应用内显示更新按钮。iPhone（及其手表应用）可再次运行 install-ios.sh 更新，也可使用 --auto 自动更新。VS Code 通过 Marketplace 更新。

Mac 阻止了应用（“无法打开”“开发者身份不明”“已损坏”）？

TokenBar 尚未经过 Apple 公证（这需要付费开发者账户），因此 macOS 会阻止首次启动从浏览器下载的应用。以下任一方法都可解决：

1. 使用上面的命令安装。 通过终端下载就不会出现警告。
2. 允许打开一次： 尝试打开 TokenBar → 系统设置 → 隐私与安全性 → 向下滚动 → 仍要打开 → 输入 Mac 密码。
3. 提示“已损坏”？ 在终端中运行：xattr -dr com.apple.quarantine /Applications/TokenBar.app，然后重新打开。

提示 “TokenBar 想要使用存储在 Claude Code-credentials 中的机密信息” 并非阻止提示：这是登录读取提示（VS Code 面板）。选择 始终允许。

也可以让 AI 帮你。 打开 Claude Code、Codex 或任何带有终端的 AI，然后说：

阅读 https://github.com/ChaconLucas/tokenbar/blob/main/INSTALL.md 并帮我安装 TokenBar。

INSTALL.md 是为 AI 编写的：它会询问你有哪些设备，运行相应命令，并且只在需要你操作时（授予权限、操作手机或手表）请你帮忙。

---

它的功能

Mac

• LED 设备窗口（可放大、缩小或全屏显示），以及始终置顶的浮动 迷你窗口，包括在全屏应用上方。
• 显示百分比：菜单栏（菜单栏中显示带百分比的小 LED 条）、刘海屏（摄像头周围的黑色胶囊，悬停即可打开）或两者。
• 点击菜单栏会打开一个摘要，其中包含玻璃质感按钮（macOS 26 上为 liquid glass）：设备、迷你窗口、设置、刷新、退出。
• 小组件（小、中、大）和 控制中心控件（macOS 26）：TokenBar、Claude、Codex、浮动窗口和设备。
• 设置分为四个标签页：常规（语言、显示内容、颜色）、AI、设备（手机和手表）、服务（本地 API、webhook、服务）。入门指南会逐步连接所有内容。

Windows 和 Linux — 同样具备 LED 设备、浮动迷你窗口、系统托盘中的 12 点圆环和入门指南（应用位于 desktop/，使用 Tauri 构建）。

iPhone

• 横屏打开、全屏显示、屏幕常亮：为你的限额打造的桌面时钟。
• 主屏幕和锁定屏幕小组件（预设加自定义；“一次一个”模式可在轻点时切换 AI）。
• 锁定屏幕和 灵动岛中的 实时活动（适用于配备灵动岛的 iPhone），并提供切换 AI 和时间窗口的按钮。
• 内置二维码扫描器（扫描二维码），可与电脑配对；更新发布或免费账户应用即将过期时也会发出通知。

Apple Watch — 应用（全部 / CLAUDE / CODEX、5 小时 / 7 天，或转动数码表冠）、表盘复杂功能，以及 智能叠放卡片（watchOS 11+ 上的实时活动，以及在限额将近或即将重置时显示的小组件）。

Android 和 Wear OS — 手机横屏显示，配有主屏幕小组件、提醒和应用内更新。Wear OS 手表可与手机配合使用，也可独立使用：单独使用时，输入电脑上显示的 6 位数代码（Mac：设置 → 设备 → WEAR OS 独立使用）。表盘复杂功能。没有 Google 服务的 Huawei 设备：无法扫描二维码，请改为粘贴链接。

AI

• Claude Code：通过终端状态栏（点击一次：连接，位于 设置 → AI），或在使用 VS Code 面板时通过其登录信息。
• Codex：自动检测，支持终端、VS Code 或 Codex 应用。
• GitHub Copilot：选择启用（每月高级请求，通过 gh auth token）。
• Windsurf：自动检测。
• Cursor、Gemini CLI、Kiro：选择启用，使用各自已保存的登录信息（Gemini：仅限 Workspace / Code Assist 账户）。
• GLM (Z.ai)、MiniMax、Kimi Code、OpenRouter、Factory Droid、Amp：在 Settings → AIs 中粘贴 API 密钥（Mac：密钥存储在 Keychain 中）。
• 通过一个小型 JSON 文件接入其他任意 AI：docs/providers.md。

其他功能

• **语言：**葡萄牙语和英语，可通过 自动 / 葡萄牙语 / 英语切换（自动模式跟随系统设置）。
• **时间窗口：**5 小时、7 天，或在同一屏幕上同时显示两者。背景会根据用量填充：用量达到 23%，就会点亮屏幕的 23%。
• 时间窗口超过 80% 和 95% 时，以及重置时发出提醒（iPhone 会将提醒同步到手表）。
• **自定义：**为每个 AI 设置颜色、文本和计时器颜色、按用量变色、达到 85% 后变红、圆点或方点、亮度。

---

API 和开发者

• 本地 API：应用运行时可用（Mac、Windows、Linux）：http://localhost:41777/v1/usage，仅限 localhost；实际端口见 ~/.tokenbar/api.json。
• 命令行工具 tokenbar：在终端中显示进度条；使用 tokenbar --prompt 设置 shell 提示符或 tmux，也可使用 tokenbar get claude 5h 编写脚本。无需运行应用也能使用。
• MCP 服务 tokenbar-mcp：Claude Code、Codex 或 Cursor 可在长任务开始前调用 check_budget。
• Webhook：在使用量达到 80% / 95% 或重置时触发（Slack 和 Discord 会收到一句说明；其他服务会收到 JSON）。
• 可读取 ~/.tokenbar/snapshot.json，无需运行应用；也可使用 ~/.tokenbar/providers/*.json 添加任意 AI。

curl -s http://localhost:41777/v1/usage

Schema 和示例（curl、JavaScript、Python、starship、tmux、zsh）：docs/api.md。

---

工作原理

                          Wi-Fi (Bonjour)                       WatchConnectivity / Wear OS
 Computer ─────────────────────────────────────► iPhone / Android ─────────────────────► Apple Watch / Wear OS
 (Mac, Windows, Linux)                             widgets, Lock Screen,                  complications
  │ Claude Code: copy of the statusline (or login)  Live Activity
  │ Codex: ~/.codex/sessions · Windsurf · Copilot · Cursor · Gemini · Kiro · GLM · MiniMax · Kimi · OpenRouter · Droid · Amp
  │ any AI: ~/.tokenbar/providers/*.json
  │
  └──── PUT ────► server (optional) ◄── GET ──── phones and watches, away from home

1. 电脑收集数据。 Claude Code 只会将限额交给 statusline；TokenBar 会安装一个小脚本（~/.tokenbar/claude-tee.sh），保存一份副本并运行你原有的 statusline，不做任何更改（并备份 settings.json）。Codex 会将限额写入 ~/.codex/sessions。
2. 在本地网络上广播（_tokenbar._tcp），并且只响应持有配对密钥的设备。
3. 手机会在同一 Wi-Fi 网络中自动发现电脑，并将数据传给手表。
4. **可选服务端：**电脑也会向服务端发送数据，手机会使用 Wi-Fi 和服务端数据中较新的数值。

隐私

• **代码、提示词或对话都不会离开电脑。**仅发送百分比、重置时间和数据读取时间。
• **Wi-Fi：**电脑只响应发送配对密钥的设备；广播内容只显示密钥的前 8 个字符。
• **本地 API：**仅监听 127.0.0.1，并拒绝其他 Host 标头。
• **登录：**Claude Code 登录令牌只会发送给 Anthropic；GitHub 令牌（Copilot）只会发送给 GitHub。两者均为只读，且默认关闭。
• **服务端：**只存储密钥的 sha256 值，不存储密钥本身，以及最新快照。
• **任何拥有二维码的人都能看到你的数据。**请勿发布二维码。

已知限制

• iPhone 需要配备 Xcode 的 Mac；使用免费的 Apple 帐户时，应用每 7 天会过期一次（使用 install-ios.sh 或 --auto 续期）。
• **macOS：**应用未经公证（参见“Mac 拦截了它？”框）。未启用沙盒，因此无法上架 Mac App Store。
• **Linux：**尚无安装包；请从源代码构建。
• **Claude Code：**Claude Code 会话运行时，数据会更新（通过 statusline），除非启用了登录信息读取。
• **非官方端点：**Claude 登录信息读取和 Copilot 使用的端点没有公开文档，可能会发生变化。
• **小组件：**iOS 和 watchOS 大约每 15 分钟刷新一次。

故障排查

症状	处理方法
手机：“Mac não encontrado no Wi-Fi”（未找到 Mac）	是否连接了同一个 Wi-Fi？iPhone：是否已开启 本地网络（设置 → 隐私与安全性 → 本地网络 → TokenBar）？电脑防火墙是否允许 TokenBar？
手机：“O Mac recusou a chave”（密钥被拒绝）	重新扫描二维码。
没有显示 Claude	设置 → IAS → CLAUDE CODE → 连接，然后在终端中的 Claude Code 里发送一条消息。
Claude 在 VS Code 面板中	状态栏不会在此处运行。请在 设置 → IAS 中开启 VS CODE 面板，或点击设备下方提示中的 开启。macOS 会询问一次：始终允许。
没有显示 Codex	使用一次 Codex；限额会随第一条回复显示。
VS Code 扩展处于受限模式	此问题已解决：扩展可在不受信任的工作区中运行。
Watch：“integrity could not be verified”（无法验证完整性）	在手表上开启开发者模式（设置 → 隐私与安全性）。
Dock 中图标空白	killall Dock。如果问题仍然存在，请重新启动 Mac。

---

从源代码构建

Mac、iPhone 和 Apple Watch（Xcode 26+ 和 brew install xcodegen）：

git clone https://github.com/ChaconLucas/tokenbar.git && cd tokenbar
printf 'DEVELOPMENT_TEAM = ABCDE12345\nTB_BUNDLE_PREFIX = com.yourname\n' > Config/Signing.local.xcconfig   # your Team ID; git ignores this file
xcodegen generate && open TokenBar.xcodeproj

构建方案：TokenBarMac（Mac）、TokenBar（iPhone，包含手表应用）、TokenBarWatch。iPhone 和手表需要开启开发者模式；首次启动时允许访问本地网络，然后在 设置 → 设备中扫描二维码进行配对。

Windows 和 Linux（Rust 和 Node 18+；Linux 还需要 sudo apt install libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev build-essential）：

cd desktop && npm install && npx tauri build    # installers in src-tauri/target/release/bundle/

Android 和 Wear OS（JDK 17 和 Android SDK）：

cd android
echo "sdk.dir=$HOME/Library/Android/sdk" > local.properties
JAVA_HOME=/opt/homebrew/opt/openjdk@17 ./gradlew :app:assembleDebug :wear:assembleDebug
adb install app/build/outputs/apk/debug/app-debug.apk                # phone
adb -s <watch> install wear/build/outputs/apk/debug/wear-debug.apk   # watch

可选服务端（在外出时查看你的数据）

不使用服务端时，手机只能在与电脑连接同一 Wi-Fi 时更新。你可以在 Cloudflare 上免费部署自己的服务端（Worker + D1）：

cd server && npm install && cp wrangler.example.toml wrangler.toml
npx wrangler login
npx wrangler d1 create tokenbar          # copy the database_id into wrangler.toml
npx wrangler d1 execute tokenbar --remote --file=schema.sql
npx wrangler deploy                      # prints https://tokenbar.<your-account>.workers.dev

将地址粘贴到 设置 → 服务端 → 地址（Windows/Linux：⚙），然后在手机上重新扫描二维码。只有数据发生变化时，电脑才会发送数据；否则每 10 分钟发送一次。

结构

App/macOS    Mac app: collector, Wi-Fi server, notch island, Mini, settings, local API, webhooks
App/iOS      iPhone app: full screen, Live Activity, guide and QR scanner
App/watchOS  Apple Watch app
Shared/      model, LED display, theme, languages, Wi-Fi client, server API
Widget/      widgets, complications, Control Center and Live Activity (Mac, iPhone, Watch)
android/     Android phone (app), Wear OS (wear) and shared code (core)
desktop/     Windows and Linux app (Tauri)
vscode/      VS Code extension
raycast/     Raycast extension
streamdeck/  Stream Deck plugin
cli/         `tokenbar` CLI and `tokenbar-mcp` server
server/      optional Cloudflare Worker + D1
scripts/     installers (Mac, iPhone, CLI) and release
docs/        images, API and providers docs

许可证

MIT。请参阅 LICENSE。

TokenBar 是一个独立项目，与 Anthropic、OpenAI、GitHub 或 Windsurf 的开发者均无关联。“Claude”“Claude Code”“Codex”“Copilot”和“Windsurf”是其各自所有者的商标。