ClaudeBurst：macOS菜单栏应用，实时监控Claude Code会话时间

1. 项目概述：一个为Claude Code用户定制的“时间管家”

如果你和我一样，是Claude Code的深度用户，那你一定对那个“5小时会话窗口”又爱又恨。爱的是，它提供了一个清晰、可预测的免费使用额度；恨的是，你永远不知道下一次额度什么时候刷新，经常在埋头写代码时，突然发现额度用尽，只能干等。这种体验，就像开车时油箱见底，却不知道下一个加油站还有多远。

ClaudeBurst就是为了解决这个痛点而生的。它是一个纯粹的macOS菜单栏应用，没有复杂的界面，不占用Dock空间，就安静地待在屏幕右上角。它的核心任务只有一个：实时监控你的Claude Code使用日志，精确计算当前会话的剩余时间，并在额度刷新时，用你选择的声音和通知提醒你——“新的5小时开始了，快回来继续工作！”

这个工具的价值在于，它将Claude Code后台的、隐性的时间规则，变成了一个前台可见、可感知的进度条和闹钟。你不再需要去猜测、去计算，或者频繁地查看Claude桌面应用。对于依赖Claude Code进行日常开发、调试或学习的开发者来说，这不仅仅是方便，更是一种工作流上的优化，让你能更专注、更高效地利用这宝贵的免费资源。

2. 核心功能与设计思路拆解

2.1 为什么选择菜单栏应用形态？

在macOS生态中，通知类工具的选择很多：有独立的桌面应用、有基于Web技术的Electron应用、也有命令行工具。ClaudeBurst选择了最经典的菜单栏应用形态，这背后有几个关键的考量：

第一，极致的轻量与无干扰。菜单栏应用通常不显示在Dock中（除非在设置中手动开启），运行时只在状态栏有一个小图标。这意味着它几乎不占用任何屏幕的“有效面积”，对用户的工作流干扰降到最低。你不需要为了看时间而切换窗口或打开一个应用，一抬眼就能看到信息，这符合“监控”类工具的核心需求——被动感知，主动提醒。

第二，系统集成度高。作为原生应用，它可以无缝使用macOS的原生通知中心（Notification Center）。当会话刷新时，弹出的横幅或提醒通知会出现在屏幕右上角，并伴有系统声音。这种集成确保了提醒的可靠性和一致性，无论你当前在哪个全屏应用或虚拟桌面中，都能收到提示。

第三，开发与维护成本。对于这样一个功能聚焦（读取日志、计算时间、发送通知）的工具，使用Swift和AppKit开发一个原生菜单栏应用，其二进制体积小、启动速度快、内存占用低，远优于功能相似的Electron应用。同时，原生应用在权限申请（如通知权限）、文件系统访问（读取~/.claude目录）上也更为直接和稳定。

2.2 会话时间计算的底层逻辑

这是ClaudeBurst最核心、也最需要理解的部分。它并非凭空猜测时间，而是基于Claude Code客户端生成的、实实在在的操作日志。

2.2.1 数据来源：Claude Code的JSONL日志

Claude Code在本地会记录用户的所有操作，这些日志以JSON Lines格式存储在你家目录下的~/.claude/projects/文件夹中。每个项目文件夹里可能有一个或多个.jsonl文件，里面按行记录了时间戳、操作类型（如code_completion、chat）等信息。

ClaudeBurst会实时监控这个目录的变化。每当有新的日志文件产生或现有文件被追加写入，它就会读取最近24小时内的日志，从中提取出所有操作的时间戳。这个“24小时”的窗口是一个合理的回溯期，既保证了能捕捉到足够的历史活动来确定会话模式，又避免了处理过多陈旧数据带来的性能开销。

2.2.2 核心算法：如何划定5小时窗口？

理解了数据来源，我们来看算法。Claude Code的免费额度是“滚动”的5小时，但这个“滚动”的起点是如何确定的？根据对Claude Code官方行为的逆向工程（主要参考了开源项目Claude-Code-Usage-Monitor的逻辑），其规则可以概括为：

1. 对齐整点（UTC时间）：会话窗口的起始时间，并不是你第一次使用Claude Code的那个精确到秒的时刻，而是会向下取整到当前小时的整点，并且是基于UTC（协调世界时）。例如，如果你在UTC时间14:30开始了第一次操作，那么你的第一个5小时会话窗口会被认定为从UTC时间14:00开始，到19:00结束。
2. 滚动刷新：当一个5小时窗口结束后，下一个窗口会立即开始。也就是说，如果你在第一个窗口内持续使用，那么额度会在窗口结束时刷新。
3. 长时间间隔后的重置：如果你在超过5小时的时间内没有任何活动，那么下一次你开始使用Claude Code时，系统会以这次活动的时间为基准，重新计算一个新的整点起始窗口。

ClaudeBurst的算法就是模拟了这套逻辑。它扫描日志，找到最近的活动时间点，然后根据上述规则，计算出“当前正在使用的会话窗口”的起止时间（UTC），并转换为你的本地时间显示在菜单栏。同时，它也能推算出“下一个会话窗口”的开始时间。

注意：这里有一个常见的理解误区。这个“5小时”指的是Claude Code服务器端记录的你使用其AI服务的时间，并非你的本地应用打开时长。它是由你的操作（如代码补全、问答）触发的，因此日志是计算的唯一可靠依据。

2.3 声音与通知系统的设计

一个有效的提醒，必须是多模态的。ClaudeBurst采用了“视觉（菜单栏）+ 听觉（声音）+ 系统通知”的三重提醒机制。

视觉层面：菜单栏图标本身就是一个状态指示器。通常，它会显示下一个会话的开始时间（如“Next: 22:00”）。当会话刷新时，虽然图标本身可能不会剧烈变化，但结合即将弹出的通知，能形成有效的视觉锚点。

听觉层面：这是“Burst”（爆发）一词的趣味体现。应用内置了一系列“鼓舞人心”或“怀旧”的提示音效，比如类似游戏升级、任务完成的短促音效。你可以在设置中选择自己喜欢的声音。声音的加入至关重要，尤其是在你戴着耳机、或视线离开屏幕时，能确保提醒被及时感知。

系统通知：这是最终的信息送达层。当检测到会话刷新时，应用会通过macOS通知中心发送一个本地通知。标题通常是“A new Claude Code session has begun!”，副标题会显示这个新会话的5小时时间范围（例如“10:00 PM - 3:00 AM”）。这个通知会停留在通知中心，即使你当时错过了，之后也可以回顾查看。

这三层设计确保了提醒的冗余度和可靠性，无论用户处于何种工作状态，总有一种方式能触达他。

3. 从下载到使用：完整实操指南

3.1 两种获取方式：直接下载 vs 自行编译

对于大多数用户，我强烈推荐直接下载预编译的版本，这是最快捷的方式。

3.1.1 直接下载安装（推荐给绝大多数用户）

1. 前往发布页面：打开项目的GitHub仓库，进入“Releases”页面，找到最新的版本（通常标记为“Latest”）。

2. 下载应用包：在发布的资源文件中，找到ClaudeBurst.app.zip文件并下载。

3. 解压与放置：下载完成后，双击zip文件解压，你会得到一个ClaudeBurst.app的文件。将其拖拽或复制到系统的/Applications（应用程序）文件夹中。这是macOS应用的标准安装位置，便于系统管理和启动。

4. 解决安全阻拦（关键步骤）：由于ClaudeBurst是开源项目，开发者可能没有购买昂贵的苹果开发者证书进行签名，因此macOS的Gatekeeper安全机制会阻止其运行。

   • 方法一（图形界面）：在/Applications文件夹中找到ClaudeBurst.app，按住Control键并点击（或右键点击），在弹出的菜单中选择“打开”。此时会弹出一个警告对话框，明确提示应用来自未识别的开发者，但会出现一个“打开”按钮。点击“打开”，应用即可启动，并且这次授权会被记住，下次直接双击就能打开。
   • 方法二（命令行）：打开“终端”（Terminal），输入以下命令并回车：

     xattr -cr /Applications/ClaudeBurst.app

     这条命令会清除应用的所有“扩展属性”，其中也包括了Gatekeeper添加的隔离属性（quarantine attribute）。执行后，你就可以像普通应用一样双击打开了。

5. 授予通知权限：首次启动应用时，macOS会弹窗请求允许发送通知。务必点击“允许”，否则你将收不到任何提醒，应用就失去了核心价值。你可以在系统设置的“通知”里，后期找到ClaudeBurst调整权限。

完成以上步骤后，你应该能在屏幕顶部菜单栏的右侧（时间、电池等图标的附近）看到一个Claude风格的图标，这表示应用已经在后台安静运行了。

3.1.2 从源码编译（适合开发者或追求绝对安全的用户）

如果你不放心预编译的二进制文件，或者想学习、修改源码，可以自行编译。这需要一些开发环境。

1. 准备环境：确保你的macOS系统版本在12.0以上，并安装了Xcode。打开终端，运行xcode-select --install来安装命令行工具。
2. 获取源码：使用Git克隆项目到本地：

   git clone https://github.com/rossshannon/ClaudeBurst.git cd ClaudeBurst

3. 执行构建脚本（最简单）：项目提供了一个便捷的build.sh脚本。
   • 仅编译：./build.sh
   • 编译并自动安装到应用程序文件夹：./build.sh --install使用--install参数非常方便，它会完成编译、清理旧版本、复制应用到/Applications并启动的全过程。
4. 使用Xcode编译（传统方式）：你也可以用Xcode打开项目根目录下的ClaudeBurst.xcodeproj文件。在Xcode中，选择菜单栏的Product->Build(或按Cmd+B)。编译产物位于build/Build/Products/Release/目录下，手动将ClaudeBurst.app复制到/Applications即可。

自行编译的应用由于是在本地生成，通常不会触发Gatekeeper的阻拦，但首次运行时同样需要授予通知权限。

3.2 基础使用与菜单详解

应用运行后，一切交互都通过菜单栏的图标完成。点击那个小图标，你会看到一个下拉菜单，里面包含了所有功能：

• Current session: [时间A] – [时间B]：这里显示的是ClaudeBurst计算出的、你当前正在使用的那个5小时会话窗口的起止时间（已转换为你的本地时间）。这是最重要的参考信息，让你知道本次额度还剩多少。
• Next session at [时间C]：显示下一个会话窗口预计的开始时间。当当前会话用完时，下一个会话就会立即变为“当前会话”。
• Settings...：打开设置窗口，这里是自定义应用的核心。
• Test Notification：手动触发一次通知和声音。强烈建议在初次安装后点一下这个选项，用于测试通知权限是否正常、声音是否是你喜欢的。
• Quit：退出ClaudeBurst应用。

3.3 个性化设置：打造专属提醒

点击菜单中的Settings...，会弹出一个简洁的设置窗口。这里有两个主要配置项：

1. Notification Sound（通知声音）：这是一个下拉选择框，里面列出了所有可用的音效。你可以逐个选择，然后点击旁边的“Preview”按钮试听。内置的音效通常比较短促、清晰，适合作为提醒。选择你最敏感或最喜欢的一个。
2. Show in Dock（在Dock中显示）：这是一个复选框。默认情况下是未勾选的，意味着应用只在菜单栏运行，Dock上不显示图标。如果你习惯从Dock点击应用，或者想确认应用是否在运行，可以勾选此选项。勾选后需要重启应用生效。

设置窗口还有一个实用的按钮：“Open Sounds Folder”。点击它会直接打开Finder，定位到~/Library/Application Support/ClaudeBurst/Sounds/这个目录。这是你添加自定义提示音的地方。

4. 高级技巧与深度定制

4.1 添加自定义提示音：让提醒更有趣

虽然内置音效不错，但谁不想用《星际争霸》里“Nuclear Launch Detected”或是《塞尔达传说》找到神庙时的声音作为提醒呢？ClaudeBurst支持非常灵活的声音定制。

原理：应用在运行时，会从两个地方合并加载声音文件：

• 内置资源（Build-time）：在项目源码的./sounds/目录下的音频文件，会在编译时被打包进应用。这部分需要修改源码并重新编译，适合想要贡献音效给开源项目的开发者。
• 用户目录（Runtime）：在~/Library/Application Support/ClaudeBurst/Sounds/目录下的音频文件。这是普通用户添加自定义声音的唯一推荐途径。

操作步骤：

1. 在设置中点击“Open Sounds Folder”，如果文件夹不存在，系统可能会自动创建。
2. 将你准备好的音频文件（支持.mp3,.wav,.m4a,.mp4格式）复制到这个文件夹。建议使用短于3秒、音量起伏不大的文件，避免惊吓。
3. 关键一步：重启ClaudeBurst应用。应用会在启动时扫描这个目录，并加载所有有效的音频文件。
4. 重新打开设置，你的自定义音效就会出现在Notification Sound的下拉列表中了，文件名（不含扩展名）就是显示的名称。

实操心得：我习惯把一些经典游戏的UI音效（如《魔兽世界》接受任务的“叮”声）放在这里。需要注意的是，应用会自动监听这个Sounds文件夹的变化。但根据我的经验，在运行时新增文件，有时下拉菜单不会立即刷新，最稳妥的方式还是重启一下应用。另外，如果自定义文件与内置文件同名，自定义文件会优先被使用。

4.2 多设备使用与会话同步

这是一个非常重要但容易被忽略的场景。很多开发者会在办公室的iMac和家里的MacBook上同时使用Claude Code。Claude Code的会话状态似乎是跟随账号，在服务端同步的，但ClaudeBurst是读取本地日志文件进行计算。

这就可能产生一个问题：你在公司电脑上用完了额度，ClaudeBurst显示会话已结束。回到家打开笔记本，本地的ClaudeBurst因为检测到长时间没有活动日志，可能会认为一个新的会话开始了，但实际上服务端的额度可能还没刷新（因为滚动窗口是基于UTC时间的连续计算）。

解决方案：项目README里提到了一句：“If you use Claude Code on multiple machines, you may need to send Claude a message to sync your existing session data.” 这句话的深层含义是，你需要在每台设备上，都通过Claude Code客户端进行一次交互（比如发送一条消息），让它在本地生成最新的日志文件。这样，ClaudeBurst读取到这份新鲜的日志，才能根据里面的时间戳，计算出与服务端同步的、准确的当前会话窗口。

所以，最佳实践是：在新设备上启动Claude Code，先随便问个问题，等它回复。这样本地日志更新后，ClaudeBurst的计时就会变得准确。

4.3 文件监控与性能影响

ClaudeBurst通过macOS的FSEventsAPI监控~/.claude/projects/目录。这意味着它不需要定时轮询，而是由操作系统在文件发生变化时主动通知应用，这是一种非常高效且省电的机制。

对于性能，你完全不用担心。我曾在活动监视器中观察过，ClaudeBurst在闲置时内存占用通常在20MB以下，CPU使用率为0%。只有在日志文件更新（即你使用Claude Code）时，才会有微小的CPU波动来解析新日志行并重新计算时间。它的资源消耗远小于一个浏览器标签页。

5. 常见问题排查与解决实录

即使设计得再完善，在实际使用中也可能遇到一些小问题。下面是我在长期使用和社区交流中总结的一些常见情况及解决方法。

5.1 通知不弹出或没有声音

这是最常见的问题，90%的原因出在系统权限或配置上。

• 检查通知权限：打开“系统设置” -> “通知”，在应用列表中找到“ClaudeBurst”。确保“允许通知”是打开的。你还可以在这里设置通知的样式（横幅或提醒）、是否播放声音等。
• 检查系统勿扰模式/专注模式：如果你的Mac设置了勿扰模式或特定的专注模式（如工作、睡眠），可能会屏蔽所有通知。检查菜单栏的控制中心，确保当前模式允许通知通过。
• 测试通知功能：在ClaudeBurst的菜单中，点击“Test Notification”。如果此时能正常弹出通知并播放声音，说明应用本身工作正常，问题可能出在触发逻辑上（见下一点）。如果测试通知也没反应，回头确认上述权限和模式设置。
• 确认声音文件：在设置中，检查“Notification Sound”是否选中了一个有效的选项。可以尝试切换回默认的“ClaudeBurst”音效测试。

5.2 菜单栏显示的时间不准或“No active session”

这通常意味着ClaudeBurst没有在日志中找到有效的活动数据来计算会话。

• 确认Claude Code正在运行并有活动：ClaudeBurst依赖Claude Code生成日志。请确保Claude Code应用已经启动，并且你最近进行过一些能触发AI服务的操作（如代码补全、在聊天框提问）。仅仅打开应用而不使用，可能不会产生新的日志。
• 检查日志目录是否存在：打开终端，输入ls -la ~/.claude/projects/查看目录。如果目录不存在，说明Claude Code可能从未在该设备上创建过项目，或者安装路径不同。你可以尝试在Claude Code中创建一个新项目并执行一次操作。
• 查看应用日志（高级）：如果上述都没问题，可以查看ClaudeBurst自身的日志来排查。通过“控制台”应用（Console.app）查看。在左侧设备列表下选择你的Mac，然后在右上角搜索“ClaudeBurst”，可以过滤出相关日志，查看是否有文件读取错误等提示。
• 重启大法：尝试退出并重新启动ClaudeBurst。有时重新读取日志目录可以解决临时性的文件句柄或缓存问题。

5.3 自定义声音不显示或无法播放

• 文件格式与路径：确保自定义声音文件放在了正确的路径：~/Library/Application Support/ClaudeBurst/Sounds/。注意“Library”是隐藏文件夹，可以通过Finder的“前往”菜单，按住Option键点击“资源库”进入，或者直接用设置里的“Open Sounds Folder”按钮。
• 文件格式支持：确认文件格式是支持的.mp3,.wav,.m4a,.mp4。有些.m4a文件如果编码特殊，可能无法播放。最稳妥的格式是.mp3或标准的.wav。
• 重启应用：添加文件后，务必重启ClaudeBurst应用，让它重新扫描并加载声音列表。
• 文件损坏：尝试用QuickTime Player等应用打开你的音频文件，确认其本身没有损坏，可以正常播放。

5.4 应用无法打开或意外退出

• macOS版本兼容性：确认你的macOS版本在12.0 (Monterey) 或以上。旧版本系统可能缺少必要的API。
• 安全性与隐私：如果是从网上下载的预编译版本，务必按照前文“解决安全阻拦”的步骤操作。如果是从源码编译，确保Xcode命令行工具已正确安装。
• 权限问题：极少数情况下，如果之前错误地修改过~/.claude目录的权限，可能导致应用无法读取。可以尝试在终端中重置目录权限（谨慎操作）：

  sudo chmod -R 755 ~/.claude

  或者检查目录的所有者是否是你的当前用户。

5.5 与其他类似工具的对比与选择

在ClaudeBurst的GitHub主页上，作者还列出了几个同类型的项目。了解它们有助于你做出最适合自己的选择。

• Claude-Code-Usage-Monitor：这是一个功能更强大的终端（Terminal）监控工具。除了基础的时间显示，它还能用图表展示使用趋势，甚至预测额度消耗速度。适合喜欢待在命令行、需要更详细数据分析的高级用户。
• ccusage：这是一个纯粹的CLI（命令行界面）工具，用于分析历史日志。它可以生成日报、月报，统计使用量和估算成本。它不提供实时监控和提醒，更像是一个事后分析工具。
• ccusage-monitor (macOS) / ccseva：这两个和ClaudeBurst一样是菜单栏应用。ccusage-monitor更偏向于API使用量和付费周期的监控；ccseva是基于Electron和React构建的。相比之下，ClaudeBurst的优势在于其极致的轻量（原生Swift）、纯粹的功能聚焦（只做会话时间提醒）以及开源可定制。

我个人选择ClaudeBurst的理由是：它完美地解决了我的核心痛点——想知道额度什么时候刷新，并且用最轻量、最不打扰的方式提醒我。我不需要复杂的图表，也不需要成本计算（因为只用免费额度），一个精准、安静的“时间管家”正是我想要的。

6. 总结与延伸思考

ClaudeBurst是一个典型的“解决单一痛点”的优秀工具。它的成功在于对用户场景的深刻理解：Claude Code用户不需要一个功能繁杂的管理中心，只需要一个可靠的时间提醒器。通过精准的日志解析、高效的文件监控、系统级的通知集成，它几乎以零成本的方式融入了我的开发工作流。

从技术实现上看，它也是一个很好的学习案例：如何为一个没有公开API的服务（Claude Code的会话状态）构建客户端工具？答案是逆向工程和日志分析。如何设计一个友好的用户界面？答案是拥抱平台原生特性（菜单栏、通知中心），做减法。如何让工具具有扩展性？答案是提供简单的自定义声音接口。

最后，这个小工具也反映了AI工具普及后的一种新需求：随着这些按使用量或时间计费的服务增多，用户对“资源可视化”和“消耗预警”的需求会越来越强。ClaudeBurst的模式或许可以被复制到其他类似的服务上。如果你也遇到了某个服务的额度“黑盒”问题，不妨想想，它的客户端是否也在本地留下了可供分析的“蛛丝马迹”呢？