steipete/CodexBar - 项目详情

项目介绍快速开始学习路径项目截图 1 贡献者 48 增长趋势代码统计生态关系项目时间线项目竞品依赖分析上榜历史

学习路径指南

难度等级

初级

预计时长

1-2小时

适合人群

macOS用户，尤其是同时使用多种AI编程助手（如GitHub Copilot、Cursor、Claude等）的开发者，希望集中监控使用额度。无需Swift编程经验即可使用，但需要基本macOS操作能力。

学习目标：学会安装、配置和使用CodexBar，在菜单栏实时监控多个AI服务的会话额度和周使用量，有效管理AI编程资源。

前置知识

macOS基础操作熟悉

需要知道如何安装应用、管理系统偏好设置和菜单栏应用。

macOS 14+ (Sonoma) 了解

应用要求操作系统为macOS 14或更高版本。

至少一种AI编程助手服务了解

需要至少使用过一种CodexBar支持的服务（如GitHub Copilot、Cursor等），并拥有相应账户或已登录。

学习步骤

环境准备与安装

15分钟

确认系统版本

点击屏幕左上角苹果菜单 → 关于本机，确认macOS版本为14.0 (Sonoma) 或更高。

如果版本过低，需要先升级系统。

下载并安装应用

访问GitHub Releases页面下载最新版本的CodexBar.dmg文件。打开dmg文件，将CodexBar应用拖拽到“应用程序”文件夹中。

推荐使用Homebrew安装：`brew install --cask codexbar`，更便捷。

首次运行与权限授予

从“应用程序”文件夹中启动CodexBar。首次运行时，macOS可能会弹出权限请求（如Keychain访问）。根据提示点击“允许”或“确定”。

应用没有Dock图标，启动后图标会出现在屏幕右上角的菜单栏。如果没看到，请点击菜单栏最右侧的“控制中心”图标查看是否被隐藏。

基础配置与核心使用

30分钟

打开设置并启用服务提供商

点击菜单栏的CodexBar图标，在下拉菜单中选择“Settings...”。在打开的设置窗口中，切换到“Providers”标签页。找到你正在使用的AI服务（如“Copilot”、“Cursor”），勾选其旁边的复选框以启用监控。

只启用你实际使用的服务，避免不必要的资源访问请求。

确保服务源可用

对于你启用的每个服务，确保其“数据源”在你的Mac上可用且已登录。例如： - **Copilot/GitHub**: 确保已通过GitHub设备流登录。 - **Cursor/Claude**: 确保浏览器（如Chrome/Safari）中已登录相应账户，或已安装官方CLI并登录。 - **Codex**: 确保已安装Codex CLI或浏览器中已登录OpenAI。

这是数据能成功获取的关键。如果某个服务显示为灰色或报错，通常是因为应用无法找到有效的登录凭证或CLI。请参考README中对应Provider的说明。

理解菜单栏图标与信息

观察菜单栏中对应服务的图标（默认每个服务一个状态项）。图标是一个双横条计量器： - **上横条**: 代表5小时/会话窗口额度。如果周额度耗尽但有积分，它会变厚显示积分。 - **下横条**: 代表周额度窗口（细线）。点击图标可以查看详细信息：剩余额度、已用量、重置倒计时。

图标变暗表示数据过期或出错。将鼠标悬停在图标上会有提示。

尝试“合并图标”模式

在设置（Settings）的“General”标签页中，找到“Merge Icons mode”并启用。观察菜单栏变化：所有启用的服务会合并成一个图标，点击后可以通过下拉菜单切换查看不同服务。

如果你启用了很多服务，这个模式可以节省菜单栏空间。

高级功能与问题排查

30分钟

配置刷新频率

在设置的“General”标签页中，找到“Refresh cadence”下拉菜单。根据你的需求选择刷新频率，如“Manual”（手动）、“1 minute”、“5 minutes”。

更频繁的刷新能获得更实时数据，但可能略微增加资源消耗。对于大多数用户，“5 minutes”是平衡的选择。

处理Keychain频繁弹窗

如果每次刷新都弹出Keychain访问请求，可以永久授权： 1. 打开“钥匙串访问”应用。 2. 在“登录”钥匙串中，搜索相关条目（如“Chrome Safe Storage”、“Claude Code-credentials”）。 3. 双击打开条目 → 点击“访问控制”标签页。 4. 勾选“允许所有应用程序访问此项目”或更安全地，点击“+”号添加`CodexBar.app`到“始终允许访问的应用程序”列表。 5. 保存更改并重启CodexBar。

详细步骤和截图可参考README的“macOS permissions”部分。优先选择只添加CodexBar，而不是允许所有应用。

排查服务无数据问题

如果某个服务一直显示“No data”或错误： 1. 确认该服务已在设置中启用。 2. 确认你已在使用该服务（如浏览器已登录、CLI已配置）。 3. 对于基于浏览器的服务（如Cursor、Droid），可能需要授予CodexBar“完全磁盘访问”权限（系统设置 → 隐私与安全性 → 完全磁盘访问）来读取Safari cookies。或者，尝试切换到使用Chrome/Firefox的cookies（如果可用）。 4. 查看应用下拉菜单或设置中是否有更具体的错误提示。

仔细阅读README中对应“Provider”的说明，了解其具体的数据获取方式（CLI、OAuth、浏览器cookies）。

探索CLI工具（可选）

CodexBar附带命令行工具。打开终端（Terminal），输入`codexbar --help`查看可用命令。例如，可以尝试`codexbar cost --provider codex`来查看本地Codex使用成本。

CLI工具适合集成到脚本或CI/CD流程中。Linux用户主要使用CLI版本。

常见错误与避坑指南

安装后找不到菜单栏图标

CodexBar是纯粹的菜单栏应用，没有Dock图标。首次启动后，图标可能被macOS菜单栏的“控制中心”区域自动隐藏。点击菜单栏最右侧（通常有Wi-Fi、电池等图标）的“控制中心”图标，查看是否在其中。也可以在“系统设置 → 控制中心”中调整菜单栏图标的显示设置。

启用了服务但一直显示“No Data”或错误

最常见的原因是CodexBar无法获取到该服务的有效身份凭证。请确保：1) 你确实在使用该服务（如浏览器已登录账户）。2) 按照README中对该Provider的描述，准备好对应的数据源（安装CLI并登录、或允许读取特定浏览器的cookies）。3) 必要时授予相应的macOS权限（如完全磁盘访问用于读取Safari数据）。

被频繁的Keychain访问请求打扰

不要每次都点击“允许”，这只会临时生效。按照README或本指南“高级功能”部分的步骤，在“钥匙串访问”应用中为CodexBar添加永久访问权限，即可一劳永逸。

担心隐私问题，认为应用在扫描整个磁盘

CodexBar采用隐私优先设计，默认只在设备上解析数据。它不会爬取你的文件系统，仅在相关功能启用时，读取有限的已知位置（如浏览器Cookies文件夹、本地JSONL日志文件）。具体细节可查阅项目GitHub的Issue #12。

下一步探索

学完基础后可以继续探索的方向：1) 深入研究特定Provider的高级配置（如为Codex配置OpenAI cookies以获取仪表板额外数据）。2) 探索和使用WidgetKit小组件，将监控信息放在通知中心。3) 如果你是开发者，可以阅读`docs/architecture.md`了解项目架构，甚至尝试遵循`docs/provider.md`的指南为CodexBar添加对新AI服务的支持。4) 了解作者相关的其他工具，如Trimmy、MCPorter。