我做了一个 Raycast 扩展来监控 Claude Code

本文也发布在

又是一个普通的下午。

终端里同时跑着 5 个 Claude Code 会话——一个在改博客、一个在写后端接口、一个在帮我 review 代码、还有两个不知道跑到哪一步了。我切来切去，根本分不清哪个在等我输入、哪个还在干活、哪个已经跑完了。

"要是有个地方能一眼看到所有会话的状态就好了。"

我去找了一圈，市面上确实有一些监控 Claude Code 的工具，但没有一个完全符合我的预期。我想要的不只是看看会话状态——我需要一个统一的地方来管理 Claude Code 的所有东西：会话、Skills、MCP 服务器、插件，而且不管我从哪个终端、哪个编辑器打开的会话，都能通过点击直接跳转回去。

既然找不到，那就自己做。

Claude Code Monitor 命令列表 — Claude Code Monitor：五个命令覆盖监控、用量、扩展管理全流程

AI 时代：想要什么就自己做

这两年最大的感受是，AI 彻底改变了"想要一个工具"和"拥有一个工具"之间的距离。

以前你有一个想法，要么等别人实现，要么自己花几个月学一套新框架从头写。大部分想法最终的归宿是——算了，凑合用吧。

现在不一样了。你只需要把需求描述清楚，Claude Code 帮你搞定剩下的。

我之前已经用 AI 写过两个 Raycast 扩展，所以当这个新需求冒出来的时候，我很自然地就开始动手了——从第一行代码到功能基本完整，就一个晚上的事。

如果你还不了解 Raycast，可以看看我之前写的《Raycast：我最喜欢的 Mac 软件》。简单来说，它是 macOS 上的效率中枢，我日常几乎所有高频操作都通过它完成。所以当我想做一个 Claude Code 的监控工具时，Raycast 是最自然的选择——它支持菜单栏常驻、键盘优先操作、原生 macOS 性能，完美符合"随时瞄一眼"的使用场景。

AI 时代，你不需要等别人来做——你就是那个"别人"。

痛点：为什么需要这个工具

终端 AI 编程助手的日常摩擦：多会话状态不可见、Token 用量无感知、插件管理麻烦、服务器状态不明 — 用终端 AI 编程助手的四个日常摩擦，每一个都不大，但加在一起就很烦

用 Claude Code 越多，积累的小摩擦就越多。单个看都不算大问题，但加在一起，每天都在消耗注意力。

多会话状态不可见，跳转回去更麻烦

这是最直接的痛点。Claude Code 跑在终端里，一个窗口一个会话。同时开好几个项目很正常——博客在改样式、插件在加功能、工具库在修 bug。但问题是，你根本看不到哪个会话在等你输入、哪个还在执行、哪个已经结束了。

更烦的是跳转。博客项目的会话开在 Zed 里，插件项目在 Warp 里跑着，还有个工具库的会话也在后台。想切回去？先得想起来哪个项目在哪个窗口，再从一堆终端里翻找。我需要的是：不管会话是从哪里打开的，都能通过点击直接跳转回去。

Token 用量没有感知

每天用 Claude Code 写代码，token 一直在跑。CLI 里倒是有个 /cost 命令，但对订阅用户来说只会告诉你"正在使用订阅额度"，连具体数字都看不到。到底哪个项目用得最多？今天的用量跟昨天比怎么样？不同模型之间的消耗分布是什么情况？这些问题，完全没有答案。

插件更新和管理麻烦

Claude Code 的插件生态越来越丰富，我装了十几个 plugins。但管理它们非常原始——想看装了哪些插件、版本是什么、有没有更新，得去翻配置文件。启用、禁用、更新、卸载，每一步都需要命令行操作。

Claude Code 插件管理界面 — 插件管理全靠命令行，升级了也不确定到底生效没有

更让人抓狂的是升级体验。好不容易升级了一个插件，结果下次启动 Claude Code 的时候发现它又回退到旧版本了。命令行告诉你"升级成功"，但你根本无法确认是不是真的升级了——没有版本对比，没有变更日志，也没有地方能一眼看到当前所有插件的实际版本。插件一多，管理就变成了纯靠记忆的体力活。

Skills 和 MCP 服务器状态不明

Skills 装完之后，怎么确认它真的生效了？是用户级别的还是项目级别的？是从哪个 plugin 安装的？更头疼的是 MCP 服务器——你配了五六个，但不知道哪个连上了、哪个需要重新认证、哪个压根就连不上。这些信息散落在不同的配置文件里，没有一个统一的地方可以看到全貌。

说到底，我需要一个控制面板——一眼看到所有会话状态、用量分布、扩展健康度。

开发过程

开发流程总览：从 PRD 规划、数据流设计到套娃式调试 — 整个开发流程：PRD 规划 → Hooks + JSONL 数据流 → Raycast 展示 → 用 AI 调试 AI

第一步：写 PRD，把需求讲清楚

用 AI 写代码，最重要的一步反而不是写代码——是把需求想清楚。

我先让 Claude Code 帮我写了一份 PRD（产品需求文档），把我想要的功能一条条列出来：会话实时监控、菜单栏常驻状态、用量统计面板、扩展管理（Plugins + Skills + MCP Servers）、一键跳转和恢复。每个功能的预期交互是什么、数据从哪来、怎么展示，都在 PRD 里写清楚了。

PRD 写好之后，后面的实现就是按照文档一个模块一个模块地推进，Claude Code 几乎不需要我再解释上下文。

第二步：调研现有方案

PRD 确定之后，我让 Claude Code 去调研了一圈：市面上已经有哪些监控 Claude Code 的开源工具？它们是怎么实现的？

调研发现，大部分现有方案的核心思路都是读 JSONL 文件。Claude Code 会把每次会话的记录实时写入 ~/.claude/projects/ 目录下的 .jsonl 文件里，包括每一轮对话的 token 数、使用的模型、时间戳等信息。解析这些文件就能还原出会话的详细数据。

JSONL 的数据很丰富，但它更适合做统计分析——token 累计、模型分布、项目对比这些。要做会话的实时状态追踪（谁在等输入、谁在执行），还需要另一个数据源。

这里就用到了 Claude Code Hooks API。Hooks 是 Claude Code 官方提供的生命周期事件机制，可以注册脚本在 SessionStart、UserPromptSubmit、PreToolUse、Stop、SessionEnd、Notification 这些事件发生时自动执行。我之前用 Claude Code 就已经接触过 Hooks，知道它能做事件驱动的状态追踪。

思路就很清楚了——Hooks 负责实时状态，JSONL 负责丰富元数据。两个数据源互补，就能搭出一个完整的监控方案。

至于为什么选 Raycast 而不是 Web 面板或者 VS Code 扩展？原因很简单：Raycast 本来就是我的效率中枢，它支持菜单栏常驻图标，不需要打开任何窗口就能瞄一眼状态。键盘操作一气呵成，不打断工作流。而且 Raycast 扩展开发用的是 React + TypeScript，我非常熟悉。

第三步：一个晚上，把功能跑通

有了 PRD 和技术方案，剩下的就是交给 Claude Code 去实现。整个系统的数据流分两条线：

Claude Code 生命周期事件
        │
        ▼
    hook.sh (Bash + 内嵌 Python)
        │
        ├── 原子文件锁 (mkdir)
        ├── 事件 → 状态映射
        ├── 异步 AI 标签生成 (Haiku)
        └── 过期会话清理
        │
        ▼
    sessions.json (实时状态)
        │
        └──────────┐
                   ▼
        Raycast Extension
          useSessions Hook
                   ▲
        ┌──────────┘
        │
    ~/.claude/projects/**/*.jsonl
        │
        └── Chunk-based 正则解析
            (256KB 固定内存)

简单来说：Hooks 捕获实时事件写入 sessions.json，JSONL 解析提供 token 和模型等元数据，Raycast 扩展把两者合并展示。技术细节——原子文件锁、chunk-based 正则解析、AI 标签生成、磁盘缓存——全是 Claude Code 自己做的选择，我只管验收能跑就行。

真正有意思的是后面的调试。自己用自己写的工具来监控 Claude Code，然后不断发现问题、修复问题：

Subagent 刷爆面板：刚跑起来，会话列表突然冒出一大堆不认识的 session。查了半天才搞明白是 Claude Code 的子代理启动也在触发 Hook，一个主会话派出十几个 subagent，面板直接炸了。加了过滤搞定。
MCP 假故障：Extensions 页面好几个 MCP 显示 "Unreachable"，但实际上跑得好好的。原来是 stdio 模式的 MCP 不该做 HTTP 健康检查。
Worktree 识别不了：一开始完全检测不出 worktree 会话，加了个正则匹配 .claude/worktrees/ 路径才搞定。
插件更新是假的：做扩展管理的时候发现一个 Claude Code 自身的 bug——插件更新时 CLI 不会先从远程仓库拉取最新版本，直接拿本地缓存比对，结果永远显示"已是最新"。我在扩展里加了一步，更新前先手动 git pull 一下 marketplace 仓库，才让插件更新真正生效。

就是这么一个"自己用→发现问题→让 Claude Code 修→继续用"的循环。用 Claude Code 写了一个监控 Claude Code 的工具，然后用这个工具来监控写这个工具的 Claude Code。套娃了属于是。

第四步：制作图标

整个开发过程中，唯一需要我手动操作的环节就是做图标。

先在 iconfont 上搜了一圈，一眼就相中了 Claude Code 的小螃蟹——这个造型太有辨识度了：

iconfont 上的 Claude Code 小螃蟹图标 — 在 iconfont 上找到的 Claude Code 小螃蟹，一眼就选定了

然后用 Raycast 官方的 Icon Maker 工具，选好配色和样式，生成了最终的扩展图标：

Raycast Icon Maker 制作扩展图标 — 用 Raycast Icon Maker 生成最终的扩展图标

除了这一步，从写代码到提交 Raycast Store，全程都是 Claude Code 在操作，我没有手动改过一行代码。

功能展示

会话监控

这是整个扩展的核心功能。打开 Claude Code Sessions，所有会话按状态分组：Active（正在执行）、Waiting for Input（等你输入）、Idle（空闲）、Ended（已结束）。

每个会话显示：项目名、AI 生成的中文标签、编辑器/终端类型、Git 分支、持续时间。如果是在 Git worktree 里运行的会话，还会显示 worktree 徽章。

Claude Code Sessions 会话列表 — 会话列表：实时状态分组、AI 标签、worktree 徽章、一键跳转

选中任意会话按回车，直接跳转到对应的编辑器窗口（支持 VS Code、Cursor、Zed、Windsurf）或终端（Terminal、iTerm2、Warp、Ghostty、kitty）。已结束的会话可以一键 resume，不需要手动敲 claude --resume。

菜单栏常驻

Claude Code Status 是一个菜单栏图标，始终显示当前活跃会话数量。颜色会根据状态变化：绿色表示有会话在执行，橙色表示有会话在等你输入，黄色表示都在空闲。

点击图标展开下拉菜单，一眼看到所有会话的项目名、终端类型、持续时间和状态。点击任意一条直接跳转。

Claude Code Monitor 菜单栏 — 菜单栏常驻：不用切窗口，一眼看清所有会话状态

这解决了我最大的痛点——不用再挨个切终端窗口了。瞄一眼菜单栏，橙色的就是在等我，绿色的就是在干活，其他的不用管。

而且有了这个状态栏之后，你会不自觉地想让它一直保持绿色——也就是说，始终有会话在跑，始终有活在干。看到全变黄了就赶紧再派个任务出去。说白了就是狠狠地榨干 Claude Code，一分钟都别让它闲着。

用量面板

Claude Code Usage 提供完整的 token 用量统计。顶部是概览表：今天、本周、本月分别用了多少 token、跑了多少个会话。

下面是每日用量趋势图（最近 7 天）、按模型分类的消耗（Opus vs Sonnet vs Haiku），以及按项目分类的用量排名——终于能看到哪个项目最吃 token 了。

Claude Code Usage Dashboard — 用量面板：Token 趋势、模型分布、项目排名一目了然

现在我时不时会看一眼这个面板，了解各个项目的 token 消耗情况。发现某个项目用量异常高的时候，还能及时调整策略——比如把一些简单任务从 Opus 切到 Sonnet。

扩展管理

Claude Code Extensions 把 Plugins、Skills、MCP Servers 三个维度统一在一个界面里。

Plugins 页面列出所有已安装的插件，显示启用/禁用状态、版本号、来源仓库。可以一键启用、禁用、更新、卸载，还能查看每个插件包含的 commands、skills、agents 和 MCP servers。

Claude Code Extensions 插件管理 — 插件管理：版本、状态、来源一目了然，告别翻配置文件

MCP Servers 页面显示所有配置的 MCP 服务器及其连接状态——Connected（已连接）、Needs Auth（需要认证）、Unreachable（不可达）。对于需要认证的服务器，可以直接打开认证链接完成授权。

MCP Servers 状态监控 — MCP 服务器状态：哪个连上了、哪个需要认证、哪个挂了，一清二楚

再也不用猜"这个 MCP 到底连上没有"了。

小插曲：账号被封了

开发过程中还出了个幺蛾子。

扩展有个功能是给每个会话自动生成中文标签，用的是 Raycast 自带的 AI 能力。调试的时候我同时开着好几个 Claude Code 会话反复测试，每个会话一启动就会调一次 Raycast AI 生成标签，短时间内请求量一下子就上去了。

然后有一天打开 Raycast，发现登不上了。邮箱登录不行，GitHub 登录也不行。

收到的封禁通知写得很吓人：永久封禁，违反服务条款第 IV、VI、VIII 条，"滥用 AI"，不予恢复。

我人都傻了。我 200 美元的 Claude 额度都没时间花完，我滥用个啥？

赶紧去 Raycast 的 Slack 社区发消息申诉，把 GitHub 仓库链接贴上去，说你们看看代码，这就是个正常的 Claude Code 监控插件，AI 调用是插件功能的一部分，不是什么滥用。

Raycast Slack 社区申诉对话 — 在 Raycast Slack 社区申诉，等了两天终于等到回复

结果赶上周末，Raycast 团队不上班。等了两天，周一 Tirta 才回复。好在态度很好，直接道歉了——说是他们的自动检测系统把插件正常的高频 AI 调用误判成了滥用行为，这种扩展驱动的调用模式他们之前没考虑到，是他们的锅。账号随即恢复。

虚惊一场。不过换个角度想，这也说明这个插件确实在认真干活——就是太勤快了点，把平台都干懵了。

写在最后

从最初的一个念头——"要是能看到所有会话状态就好了"——到现在的 Claude Code Monitor，核心功能就一个晚上搞定。这就是 AI 辅助开发的真实体验：一个包含会话监控、用量统计、扩展管理、菜单栏常驻的完整工具，从想法到可用，快得超出预期。

这就是 AI 时代给普通开发者的礼物：你的生产力边界，不再由你会什么技术栈决定，而是由你想解决什么问题决定。

项目已经开源，MIT 协议，欢迎使用和贡献：

GitHub：wuyuxiangX/claude-code-monitor

如果你也是 Claude Code 的重度用户，不妨试试。如果它不完全符合你的需求——没关系，自己做一个。你现在有这个能力了。