steipete--codexbar/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

CodexBar 🎚️ — 愿你的 token 永不枯竭。

所有 AI 编程额度限制，尽在你的菜单栏。

一款轻量的 macOS 14+ 菜单栏应用，可让 AI 编程提供商的额度限制 始终可见，并显示各窗口何时重置。支持 Codex、OpenAI、Claude、Cursor、Gemini、Copilot、Grok、GroqCloud、ElevenLabs、Deepgram、z.ai、MiniMax、Kiro、Zed、Vertex AI、Augment、OpenRouter、LiteLLM、LLM Proxy、Codebuff、Command Code、AWS Bedrock 以及许多较新的编程提供商。每个提供商一个状态项，或使用带提供商切换器的 Merge Icons 模式。无 Dock 图标，极简 UI，动态菜单栏图标。

为何使用

• 围绕重置周期做计划。 按提供商显示会话、每周与每月窗口，并倒计时至下次重置——不再猜测是否该启动那项耗时任务。
• 积分、支出与成本扫描。 积分余额、Admin API 支出仪表盘、提供商账单摘要，以及在数据源暴露足够细节时的本地成本扫描。
• 实时状态。 提供商状态轮询在菜单中显示事故徽章，并在菜单栏图标上叠加指示器。
• 隐私优先。 复用现有提供商会话——OAuth、设备流、API 密钥、浏览器 Cookie、本地文件——因此不存储密码。

安装

系统要求

• macOS 14+ (Sonoma)

GitHub Releases

下载：https://github.com/steipete/CodexBar/releases

Homebrew

brew install --cask codexbar

CLI 压缩包（macOS/Linux）

Homebrew formula（目前支持 Linux）：

brew install steipete/tap/codexbar

Arch Linux AUR 软件包：

yay -S codexbar-cli

或从 GitHub Releases 下载发布版压缩包：

• macOS: CodexBarCLI-v<tag>-macos-arm64.tar.gz, CodexBarCLI-v<tag>-macos-x86_64.tar.gz
• Linux (glibc): CodexBarCLI-v<tag>-linux-aarch64.tar.gz, CodexBarCLI-v<tag>-linux-x86_64.tar.gz
• Linux (static musl): CodexBarCLI-v<tag>-linux-musl-aarch64.tar.gz, CodexBarCLI-v<tag>-linux-musl-x86_64.tar.gz

首次运行

• 打开「设置 → 提供商」，启用你使用的提供商。
• 安装/登录你所依赖的提供商数据源：CLI、浏览器会话、OAuth/设备流、API 密钥、本地应用文件或提供商应用，具体取决于提供商。
• 可选：设置 → 提供商 → Codex → OpenAI cookies（自动或手动），以添加仪表盘增强功能。

从 CLI 设置 API 密钥

提供商开关与 API 密钥保存在已解析的 CodexBar 配置文件中。新安装使用 ~/.config/codexbar/config.json；已有的 ~/.codexbar/config.json 安装仍从旧路径加载。你可以 编写脚本，使用与「设置 → 提供商」相同的提供商列表：

codexbar config providers
codexbar config enable --provider grok
codexbar config disable --provider cursor

对于 API 密钥类提供商，无需打开设置即可存储密钥：

printf '%s' "$ELEVENLABS_API_KEY" | codexbar config set-api-key --provider elevenlabs --stdin

set-api-key 会修剪管道传入的值，以受限的配置文件权限存储，并默认启用该提供商。使用 --no-enable 仅保存密钥，或使用 --api-key <key> 用于一次性本地脚本（无需担心 shell 历史记录）。 完整流程请参阅 CLI 配置。

提供商

• Codex — OAuth API 或本地 Codex CLI，另可选 OpenAI 网页仪表盘增强功能。
• OpenAI — 使用 Admin API 密钥的用量/成本图表，并回退到旧版积分余额。
• Azure OpenAI — API 密钥、端点与部署校验探测。
• Claude — OAuth API、浏览器 Cookie 或 CLI PTY 回退；在可用时显示会话与周用量。
• Cursor — 浏览器会话 Cookie，用于套餐、用量与账单重置。
• OpenCode — 浏览器 Cookie，用于工作区订阅用量。
• OpenCode Go — 浏览器或本地 SQLite 数据，用于 Go 用量窗口。
• Alibaba Coding Plan — 网页 Cookie 或 API 密钥，用于编码计划配额。
• Alibaba Token Plan — 百炼浏览器/手动 Cookie，用于 token 计划积分。
• Gemini — 基于 OAuth 的配额 API，使用 Gemini CLI 凭据（无需浏览器 Cookie）。
• Antigravity — 本地 language server 探测（实验性）；无需外部认证。
• Droid — 浏览器 Cookie + WorkOS token 流程，用于 Factory 用量与账单。
• Copilot — GitHub 设备流 + Copilot 内部用量 API。
• Devin — Chrome localStorage 会话或手动 Bearer token，用于每日与每周配额。
• z.ai — API token，用于个人/团队配额、MCP、5 小时与按小时用量窗口。
• Manus — 浏览器 session_id 认证，用于积分余额、月度积分与每日刷新跟踪。
• MiniMax — API token、Cookie 标头或浏览器 Cookie，用于编码计划用量。
• T3 Chat — 捕获浏览器 Cookie，用于 Base 与 Overage 用量桶。
• Kimi — 认证 token（来自 kimi-auth Cookie 的 JWT），用于每周配额 + 5‑小时速率限制。
• Kimi K2（非官方） — 旧版 API 密钥流程，用于基于积分的用量总计。
• Kilo — API token，CLI 认证回退，用于 Kilo Pass 用量。
• Kiro — 基于 CLI 的用量；月度积分 + 奖励积分。
• Vertex AI — Google Cloud gcloud OAuth，从本地 Claude 日志跟踪 token 成本。
• Augment — Augment CLI 或浏览器 Cookie，用于积分跟踪与用量监控。
• Amp — 基于浏览器 Cookie 的认证，跟踪 Amp Free 用量。
• Ollama — API 密钥访问，外加浏览器 Cookie，用于 Ollama Cloud 用量窗口。
• Synthetic — API 密钥配额端点，用于滚动 5 小时、每周 token 与搜索按小时用量。
• JetBrains AI — 来自 JetBrains IDE 配置的本地 XML 配额；月度积分跟踪。
• Warp — API token，用于 GraphQL 请求限制与月度积分。
• ElevenLabs — API 密钥，用于字符积分与语音位用量。
• OpenRouter — API token，用于跨多个 AI 提供商的基于积分的用量跟踪。
• CrossModel — API 密钥钱包余额，含每日、每周与每月支出。
• Windsurf — 导入浏览器 localStorage 会话或本地 SQLite 缓存，用于套餐用量。
• Zed — Zed 编辑器 Keychain 会话，用于套餐、编辑预测配额、账单周期与逾期发票。
• Perplexity — 来自 Perplexity 用量数据的账户用量积分。
• Xiaomi MiMo — 浏览器 Cookie，用于余额与 token 计划用量。
• Doubao — API 密钥，用于火山引擎 Ark 请求限制探测。
• Sakana AI — 手动 Cookie 标头，用于 5 小时与每周配额窗口。
• Abacus AI — 浏览器 Cookie 认证，用于 ChatLLM/RouteLLM 计算积分跟踪。
• Mistral — 浏览器 Cookie，用于 API 支出、积分余额与月度套餐用量。
• DeepSeek — API 密钥，用于积分余额跟踪（付费 vs. 赠送明细）。
• Moonshot / Kimi API — API 密钥，用于 Moonshot/Kimi API 账户余额跟踪。
• Venice — API 密钥，用于 DIEM 或 USD 余额跟踪。
• Codebuff — API token（或 ~/.config/manicode/credentials.json），用于积分余额 + 每周速率限制。
• Crof — API 密钥，用于美元积分余额与请求配额跟踪。
• Command Code — 浏览器或手动 Cookie，用于 Command Code 账单的月度 USD 积分。
• Qoder — 浏览器或手动 Cookie，用于 Qoder 大模型积分用量。
• StepFun — 用户名 + 密码登录，用于 Step Plan 速率限制（5 小时 + 每周窗口）与订阅套餐名称。
• AWS Bedrock — AWS 访问密钥或命名 AWS profile（通过 AWS CLI 的 SSO/assume-role），用于 Cost Explorer 支出、月度预算与可选 CloudWatch Claude 活动。
• Grok — Grok CLI 账单 RPC，外加 grok.com 浏览器会话回退。
• GroqCloud — API 密钥，用于 Enterprise Prometheus 请求/token/缓存命中指标。
• LLM Proxy — API 密钥 + base URL，用于聚合代理配额统计与提供商明细。
• ClawRouter — API 密钥，用于月度预算、支出、请求、token 与路由提供商用量。
• sub2api — 自托管网关密钥配额、订阅限制、钱包余额与按密钥用量。
• Wayfinder — 本地路由器网关轮询，用于健康状态、按路由明细、节省与决策延迟。
• LiteLLM — 虚拟密钥 + 代理 URL，用于个人与团队预算/支出跟踪。
• Deepgram — API 密钥用量摘要，涵盖语音、agent、token 与 TTS 指标。
• Poe — API 密钥，用于当前积分余额与近期积分历史。
• Chutes — API 密钥，用于订阅用量、滚动与月度配额窗口，以及按量付费配额。
• 欢迎新增提供商：提供商编写指南。

Icon & Screenshot

菜单栏图标是一个小巧的用量指示器。条形图的含义因提供商（provider）而异；错误或过期数据会使图标变暗或显示事件指示器。

Features

• 多提供商菜单栏，支持按提供商单独开关（Settings → Providers）。
• 各提供商专用用量指示器，带重置倒计时。
• 可选 Codex 网页仪表板增强（代码审查剩余次数、用量明细、额度历史）。
• 针对 OpenAI、Claude Admin API、OpenRouter、LiteLLM、z.ai、MiniMax、Mistral 和 AWS Bedrock 等 API 提供商的内联支出与用量图表。
• 可配置的 Codex + Claude 成本用量扫描，并为支持的提供商历史复用图表 UI。
• 提供商状态轮询，在菜单和图标叠层中显示事件徽章。
• Merge Icons 模式，将多个提供商合并为一个状态项 + 切换器。
• 显示控制：提供商图标、标签、条形图、重置时间样式，以及最高用量自动选择。
• 刷新频率预设（手动、1m、2m、5m、15m）。
• 内置 CLI（codexbar），用于脚本和 CI（本地成本用量可使用 codexbar cost --provider codex、claude 或 both）；提供 macOS 和 Linux CLI 构建。
• 为支持的提供商提供 WidgetKit 小组件。
• 应用和网站本地化，共享 21 种语言目录，支持自动网站检测、持久化选择器和 RTL。
• 可选会话配额通知和每周重置 confetti 庆祝效果。
• 隐私优先：默认在设备端解析；浏览器 cookie 需主动启用并复用（不存储密码）。

Privacy note

担心 CodexBar 会扫描你的磁盘吗？它不会遍历文件系统；在相关功能启用时，只会读取少量已知位置（浏览器 cookie/本地存储、提供商配置文件、本地 JSONL 日志）。提供商令牌和令牌账户设置保存在 CodexBar 配置文件中，并采用严格的文件权限。讨论与审计说明见 issue #12.

macOS permissions (why they're needed)

• Full Disk Access（可选）：仅在为基于网页的提供商读取 Safari cookie/本地存储时需要。若不授予，可改用其他受支持浏览器、手动 cookie/API 密钥、OAuth，或该提供商支持的 CLI/本地数据源。
• Keychain 访问（由 macOS 提示）：
  • Chromium cookie 导入需要浏览器的 “Safe Storage” 密钥来解密 cookie。
  • 当 CodexBar 没有可用缓存凭据时，Claude OAuth 引导可能会读取 Claude CLI 的 Keychain 条目。
  • CodexBar 可能将 Keychain 用于浏览器 cookie 解密、缓存的 cookie 标头，以及 OAuth/设备流凭据（当这些数据源需要时）。
  • 如何阻止这些 Keychain 弹窗？
    • 打开 Keychain Access.app → 登录钥匙串 → 搜索被提示的条目（Claude OAuth 通常为 “Claude Code-credentials”）。
    • 打开该条目 → Access Control → 在 “Always allow access by these applications” 下添加 CodexBar.app。
    • 建议仅添加 CodexBar（除非你希望完全放开，否则避免 “Allow all applications”）。
    • 保存后重新启动 CodexBar。
    • 参考截图：
  • 如何对浏览器做同样设置？
    • 找到浏览器的 “Safe Storage” 密钥（例如 “Chrome Safe Storage”、“Brave Safe Storage”、“Microsoft Edge Safe Storage”）。
    • 打开该条目 → Access Control → 在 “Always allow access by these applications” 下添加 CodexBar.app。
    • 这样 CodexBar 解密该浏览器 cookie 时就不会再弹窗。
  • 最后手段——彻底停止所有 Keychain 读取：若 “Always Allow” 无法持久（例如 Chromium 更新或 partition_id 重置后 macOS 会重置 ACL），打开 CodexBar → Settings → Advanced → Keychain access 并启用 Disable Keychain access。CodexBar 将不再访问 Keychain。基于浏览器 cookie 的提供商会被跳过，但通过 CLI 的 Claude/Codex OAuth 仍可用（它读取 ~/.codex / ~/.claude 配置文件，而非 Keychain）。
  • 卸载后仍弹窗？ 删除应用会阻止从该 bundle 再次启动，但已在运行的 CodexBar 进程可能继续请求 Keychain 访问，直到退出。请检查该进程、登录项、另一份已安装副本，或弹窗中是否指向不同的请求二进制/路径。安全排查及支持报告中应包含哪些信息（无需泄露密钥），见 Keychain prompt troubleshooting。
• Files & Folders 提示（文件夹/卷访问）：CodexBar 会为部分提供商启动提供商 CLI 和本地探测。若这些辅助程序读取项目目录或外置磁盘，macOS 可能要求 CodexBar 访问该文件夹/卷（例如 Desktop 或外置卷）。这由辅助程序的工作目录驱动，而非后台磁盘扫描。
• 我们不会在后台请求的内容：不请求屏幕录制或辅助功能权限；用户触发的辅助操作可能要求 macOS 授予自动化权限以打开 Terminal。不存储密码（在你主动启用时会复用浏览器 cookie）。

Docs

• 提供商概览：docs/providers.md
• 提供商编写指南：docs/provider.md
• Issue 标签指南：docs/ISSUE_LABELING.md
• UI 与图标说明：docs/ui.md
• CLI 参考：docs/cli.md
• 配置：docs/configuration.md
• Keychain 弹窗：docs/keychain-prompts.md
• CLI 配置：docs/cli-configuration.md
• 小组件：docs/widgets.md
• 架构：docs/architecture.md
• 刷新循环：docs/refresh-loop.md
• 状态轮询：docs/status.md
• Sparkle 更新：docs/sparkle.md
• 打包：docs/packaging.md
• 开发：docs/DEVELOPMENT.md
• 发布清单：docs/RELEASING.md
• 更新日志：CHANGELOG.md

Getting started (dev)

• 克隆仓库并在 Xcode 中打开，或直接运行脚本。
• 启动一次后，在 Settings → Providers 中切换提供商。
• 安装/登录你依赖的提供商数据源（CLI、浏览器 cookie、OAuth/设备流、API 密钥，或本地应用/配置文件）。
• 可选：为 Codex 仪表板增强功能设置 OpenAI cookie（Automatic 或 Manual）。

Build from source

需要 macOS 14+ 和 Swift 6.2+。

./Scripts/package_app.sh        # builds CodexBar.app in-place with ad-hoc signing
open CodexBar.app

Dev loop:

./Scripts/compile_and_run.sh
./Scripts/compile_and_run.sh --test  # also run the sharded test suite before packaging/relaunching
make check                           # SwiftFormat + SwiftLint
make docs-list                       # list docs with frontmatter summaries

CLI install:

# after installing CodexBar.app in /Applications
./bin/install-codexbar-cli.sh

Related

• ✂️ Trimmy — “Paste once, run once.” 将多行 shell 片段压平，便于粘贴并运行。
• 🧳 MCPorter — 面向 Model Context Protocol 服务器的 TypeScript 工具包 + CLI。
• 🧿 oracle — 卡住时问问 oracle。使用自定义上下文和文件调用 GPT-5 Pro。

Looking for a Windows version?

• Win-CodexBar

Linux desktop integration?

• codexbar-waybar — Waybar 自定义模块 + GTK4 弹出层，适用于 Hyprland / Sway / 其他 Wayland 合成器，基于内置 Linux CLI 构建。
• Codexbar GNOME — GNOME Shell 扩展，将 CodexBar 用量显示到桌面面板。
• codexbar-cinnamon-applet — Linux Mint Cinnamon 面板小程序，由 CodexBar 的 JSON 输出驱动。
• noctalia-codex-usage — Noctalia/Quickshell 插件，显示 Codex 5 小时与每周用量上限，基于内置 Linux CLI 构建。
• KodexBar — KDE Plasma 小组件，在 Plasma 面板中显示 CodexBar 用量，基于内置 Linux CLI 构建。
• codexbar-plasmoid — KDE Plasma 6 小组件，展示 CodexBar 的计量图标、提供商切换器、配额窗口、节奏、额度、本地成本与状态，由内置 Linux CLI 驱动。

状态栏与终端集成

• showy-quota — 为 SketchyBar、tmux 和 Zellij 提供常驻 AI 套餐配额条（独立 WASM 插件），基于 codexbar serve / 捆绑 CLI 构建。

致谢

受 ccusage (MIT) 启发，尤其是其成本用量追踪功能。

许可证

MIT • Peter Steinberger (steipete)