用了大半天的 Claude Code 并行任务，我一直在等一个反馈：到底还有几个 Subagent 在跑，哪个子任务快收尾了，哪个卡了很久没动静。默认界面并非没有信息，但它们都埋在日志和事件流里，你得切出去翻会话文件才知道。这种状态不透明带来的焦虑，在长任务里非常消耗注意力。所以我自己写了一套自定义状态栏工具，把 Claude Code 当前会话的 Subagent 状态直接钉在终端底部，顺带和 tmux 的状态栏打通，一眼看完不折腾。这套工具从安装到配置，再到核心实现，都不复杂，适合日常用 Claude Code 处理多文件改造、自动化代码审查、批量重构这类场景的开发者。这篇文章把整个思路和实操完整记录下来，你完全可以照着复现，再按自己的习惯改。
1. 为什么单独做状态栏工具
1.1 默认界面里 Subagent 的可见性其实很弱
Subagent 是 Claude Code 的一种任务分发机制，主 Agent 把任务拆成若干子任务交给独立的辅助 Agent 去执行，等它们跑完再汇总结果。听起来很省事，但实际跑起来之后，真正让人头疼的不是任务调度本身，而是“我不知道这些 Subagent 现在都干到哪一步了”。
倒不是说 Claude Code 完全不给你信息。在交互界面和会话日志里，Subagent 的启动、工具调用、最终结果都有记录。问题在于这些信息是以事件流的形式存在的，你必须主动去翻、去追、去对比时间戳。短任务还好，几秒钟就回来了，等一等无所谓。但一旦任务变成“改 20 个文件”“批量跑测试并修复失败用例”这种节奏，一个 Subagent 可能跑几分钟甚至更久，你盯着空白终端干等，心里完全没底。
更麻烦的是多个 Subagent 并行时，你其实很想知道资源有没有空转。比如两个 Subagent 都在跑同一类代码分析，其中一个早就完成了，但主 Agent 还在等另一个，这种阻塞关系在默认界面上看不出来。我最初的想法很简单：把 Subagent 的活跃数量、累计完成数、最近状态变化梳理成一行文字，放在固定的状态栏区域，让信息随时可见。
注意：这里说的状态栏不是 Claude Code 内置的功能，而是我们自己搭的一套终端侧显示组件。它读取 Claude Code 落盘的事件数据，解析之后重新渲染，不修改 Claude Code 本身的任何行为。
1.2 状态栏应该展示什么
动手之前我先列了需求，避免把状态栏做成一个什么都堆上去的“控制台怪物”。最终只保留了四类核心信息：
- 当前活跃的 Subagent 数量。
- 本轮会话里已经完成的 Subagent 数量。
- 最近一个结束的 Subagent 任务名和结果。
- 运行中的子任务名称清单，按启动时间排序。
活跃数量解决“还有没有事在跑”的问题；完成数量解决“这轮任务到底推进了多少”的问题；最近结束的任务名解决“刚才出去的结果是什么”的问题；运行中的任务清单则为了快速定位某个迟迟不结束的子任务。
这四项正好覆盖了我日常使用中的高频疑问。至于 token 消耗、模型名称、上下文窗口占用这些指标，Claude Code 自己的界面已经给得比较清楚，我犯不着在状态栏里再重复一遍。状态栏信息越精简，越不容易被忽略。
1.3 技术方案的取舍
接下来要决定去哪拿数据。最开始我考虑的是直接调 Claude Code 的接口拿运行状态，但现实是这类信息并没有稳定暴露给外部工具，正规路径也未必允许我随便读取一个运行中会话的内部状态。退一步想，本地会话数据其实是现成的：Claude Code 会把当前会话的事件追加写入特定目录下的 JSON Lines 文件，扩展名通常是.jsonl。只要持续跟踪这个文件的新增内容，就能还原出 Subagent 的启停过程。
渲染端的选择也有两条路。一条是直接在普通终端里用 ANSI 转义序列覆写屏幕底部的最后一行，简单直接；另一条是接入 tmux 状态栏，让状态文本出现在 tmux 底部的 status 区域。我最终两条都实现了，默认走 tmux 状态栏通道，因为我的实际工作环境就是 tmux，而且 tmux 自带刷新机制和颜色配置，稳定性和可读性都更好。
整体工具采用 Python 编写，单文件入口，不依赖重型框架。原因很简单：这类工具的生命周期很短，一个循环、一个文件指针、一个渲染函数就够，搞成复杂的工程反而维护成本高。另一个重要考量是启动速度，tmux 每几秒就要执行一次状态脚本，如果脚本启动就要几百毫秒，状态栏会一直闪烁，所以轻量是硬要求。
2. 安装和准备
2.1 环境要求
这个工具我日常跑在 Linux 和 macOS 两类系统上，核心依赖只有 Python 3.9 以上和 tmux（如果你要用 tmux 状态栏通道）。Python 的标准库就能完成文件读取、JSON 解析和基础输出，不需要额外装第三方解析库。读取文件变化我用的是自己实现的增量轮询，而不是操作系统层面的文件事件监听，这样能避开不同系统之间文件监听工具的差异，部署起来更省心。
硬件上没有任何特别要求。它只读取文本、打印文本，不占用计算资源，实测在普通开发笔记本上跑一整天的 CPU 占用几乎可以忽略。唯一要留意的是如果你同时开了非常多会话目录，不要用全目录扫描的方式找最新日志，否则状态栏刷新会变慢。
2.2 核心数据源：会话 JSONL 文件
想要做出可复现的状态栏，首先要理解 Claude Code 把状态写到了哪里。以我的实际环境为例，会话数据默认存放在当前用户目录下的~/.claude/projects/里面，每个项目目录对应一条工程路径的编码，目录内每轮会话保存为一个.jsonl文件。
文件里的每一行都代表一个事件，包括用户输入、模型回复、工具调用等。我关心的 Subagent 启停事件也在其中。拿我自己的会话日志举例，简化后的结构大概是这样：
{"timestamp": 1720000000, "type": "subagent_start", "session_id": "abc123", "subagent": {"name": "demo-reviewer", "task": "检查当前分支的代码规范问题", "model": "claude-sonnet"}} {"timestamp": 1720000100, "type": "subagent_end", "session_id": "abc123", "subagent": {"name": "demo-reviewer", "status": "success", "duration_ms": 100000}}当然，这只能代表我当前观测到的事件结构，Claude Code 的日志字段在不同版本里可能会动，字段名也可能有差异。你在实际写解析逻辑时，一定要先拿自己的日志文件跑几行jq或直接打开文件确认结构，不要照搬别人博客里的字段名就写了死代码。
2.3 安装工具
整个工具的安装可以压缩成三步：把代码放到固定目录、创建虚拟环境、测试命令行入口。下面以我本机的路径/home/demo/statusbar为例。
mkdir -p /home/demo/statusbar cd /home/demo/statusbar python -m venv .venv source .venv/bin/activate这个项目本质上只有一个脚本，核心依赖就是标准库，所以虚拟环境里不用安装什么第三方包。你可以直接把主脚本命名为claude_statusbar.py，再加上一个config.json放可调参数。命令行入口我做得比较直接：
python claude_statusbar.py --watch--watch表示持续刷新状态栏。如果要输出一次后立即退出，则不加这个参数，这对 tmux 集成很重要，因为 tmux 会周期性调用脚本拿到最新文本。
2.4 第一次运行验证
安装完先别急着接 tmux，直接手动跑一次，确认能正常识别会话日志。可以先执行：
python claude_statusbar.py --once如果输出类似下面这样，说明数据读取链路是通的：
active: 1 | done: 3 | last: demo-reviewer(success) | running: [demo-fixer]如果输出为空，先检查~/.claude/projects/下有没有最近的.jsonl文件，以及当前用户有没有读取权限。这一步能过滤掉大部分环境问题，之后接 tmux 才不会被“无输出”这种问题绕晕。
注意：状态栏工具最好用独立的虚拟环境运行，不要图省事直接
pip install到全局环境。虽然这工具依赖少，但全局环境一旦被其他项目污染，版本冲突排查起来非常浪费时间。
3. 核心实现细节
3.1 增量读取会话日志
Subagent 状态是从事件流重建出来的，所以读取日志的方式直接决定状态是否正确。最笨的办法是每次刷新都从头扫整个文件，小文件没问题，但会话时间一长，.jsonl很容易涨到几十 MB，哪怕 Python 读写很快，每秒扫一次也划不来。
所以我用文件指针偏移量来追踪进度。每次启动时，通过os.path.getsize()拿到目标文件当前大小，把指针放到末尾，只处理新增内容。脚本循环里保存一个last_offset变量，每次读取时从旧指针开始，读到当前文件末尾为止，读完更新指针。
import json import time import os LOG_PATH = os.path.expanduser("~/.claude/projects/demo/latest_session.jsonl") last_offset = os.path.getsize(LOG_PATH) def read_new_events(): global last_offset events = [] with open(LOG_PATH, "r", encoding="utf-8") as f: f.seek(last_offset) for line in f: line = line.strip() if line: try: events.append(json.loads(line)) except json.JSONDecodeError: continue last_offset = f.tell() return events这段代码有一个隐含前提：只有新行会被解析，所以即使日志里混入半行写入的残留内容，也会因为 JSON 解析失败而被跳过，不会影响整体流程。实际线上观察下来，这种简单策略非常稳。
3.2 统计 Subagent 的活跃状态
拿到增量事件之后，下一步是把事件翻译成状态。我在脚本里维护两个核心结构：一个是计数器，统计活跃数和完成数；另一个是字典，保存“运行中的 Subagent 名 -> 启动时间”，这样能随时输出正在运行的任务清单。
伪代码逻辑如下：
state = { "active": 0, "done": 0, "failed": 0, "running_tasks": {}, "last_finished": None, } for event in events: etype = event.get("type") sub = event.get("subagent", {}) if etype == "subagent_start": state["active"] += 1 state["running_tasks"][sub.get("name")] = event.get("timestamp") elif etype == "subagent_end": state["active"] = max(0, state["active"] - 1) if sub.get("status") == "success": state["done"] += 1 else: state["failed"] += 1 state["running_tasks"].pop(sub.get("name"), None) state["last_finished"] = sub.get("name")这段逻辑里最容易翻车的地方在事件配对。一个 Subagent 的启动事件和结束事件之间，可能隔着大量其他日志行，如果只按顺序计数，某个事件重复或丢失就会导致活跃数逐渐漂移。比如日志文件被手动清空过、或者旧会话被重复读取，计数就会不准。为了让状态更可靠，我加入了“按 session_id 过滤”的逻辑：只统计当前会话目录里对应 session 的事件，避免多个会话混在一起污染状态。你如果也用同一套方案，建议在自己的解析逻辑里同样加上 session 过滤，不要图省事全量统计。
提示：
failed和done分开统计是有意为之。失败信息不该被简单吞进完成数里，否则你会以为所有子任务都顺利结束了，实际上某个代码审查任务已经因为上下文超限或工具调用异常而中断。
3.3 渲染输出与 tmux 状态栏对接
状态算出来后，最后一步是把它渲染成人能直接读的文字。我设计了一个默认输出模板：
Subagent 2/5 | done 3 fail 1 | running: demo-fixer, demo-tester这里的2/5表示当前活跃 2 个，这轮共 5 个。如果运行中的任务列表太长，我会截断到前三个名字，后面加...，避免状态栏被塞满。
tmux 状态栏的对接方式非常直接。tmux 的status-right选项支持引用外部命令的输出，tmux 会按设定的刷新间隔周期性执行命令，然后把标准输出显示在状态栏右侧。我现在用的是这样的配置：
set -g status-right "#(python3 /home/demo/statusbar/claude_statusbar.py --once)" set -g status-interval 2 set -g status-right-length 120--once模式只打印一行状态并退出，速度很快，再配合status-interval 2每两秒刷新一次，基本能做到实时感知。如果你也用 tmux，建议把status-right-length调大一点，否则状态栏右侧会被 tmux 默认的窗口列表截断。
3.4 刷新策略与性能取舍
我在实现里选的是轮询，不是文件系统监听。轮询的好处是简单可靠，不依赖inotify或 macOS 的FSEvents。直接把刷新间隔参数暴露在配置里，默认 2 秒。实际测试下来，每轮循环只读取新增字节并解析少量 JSON，CPU 占用可以忽略。
但轮询有个必须注意的点：读取日志时，Claude Code 可能正在写入同一个文件，你读到的最后一行可能是半截。我处理的方式是遇到 JSON 解析失败就跳过这一行，下一个刷新周期再从校正后的偏移量继续读。偏移量维护基于f.tell()，每次只前进到已经完整解析的位置，这样半行数据不会导致后续内容错乱。
如果你把状态栏直接集成到 tmux，还要避免一个隐性坑：tmux 每次调用脚本都会重新启动一个 Python 进程，脚本启动越快，状态栏刷新越流畅。所以不要在脚本里 import 重量级库，也尽量不要在脚本启动时扫描整个目录。启动后几十毫秒内必须完成读取和输出。
4. 配置说明与应用场景
4.1 配置文件字段
我把可调参数集中放在脚本同目录的config.json里，这样改刷新间隔或显示格式时不用动代码。一个典型配置如下：
{ "projects_dir": "~/.claude/projects", "session_filter": "demo", "interval_seconds": 2, "max_running_tasks": 3, "format": "Subagent {active}/{total} | done {done} fail {failed} | {running}" }projects_dir指向 Claude Code 的会话根目录。session_filter用于只关心名称包含指定关键词的会话目录，避免多个项目混在一起。interval_seconds是轮询间隔，也是状态刷新频率。max_running_tasks控制运行中任务列表最多显示几个。format是输出模板，支持占位符替换。
这里的核心设计思路是把“数据怎么统计”和“数据怎么展示”分开。统计逻辑负责算数字，展示逻辑负责排版，这样想改成 JSON 输出或推送到系统通知时，不需要动统计代码。
4.2 把状态栏装进 tmux
接入 tmux 是我个人最推荐的做法，因为 tmux 本身就常驻终端底部，不会遮挡其他界面。除了前面提到的status-right配置，还可以把状态栏显示为单独颜色：
set -g status-style "bg=#222222,fg=#d0d0d0" set -g status-right "#(python3 /home/demo/statusbar/claude_statusbar.py --once)" set -g status-right-style "bg=colour52,fg=colour255"把status-right-style的背景色和文字色单独设置后，Subagent 状态在视觉上会和 tmux 默认信息区分开，一眼就能找到。如果你想把它放在左侧，把status-right换成status-left即可，配置方式完全一样。
还有一种更“少打扰”的集成方式：直接把状态写成 tmux 窗口标题。在 tmux 里可以这样绑定：
set -g automatic-rename on但这会覆盖原有窗口名，我试过一阵之后还是放弃了这个方案，毕竟窗口名经常用来标记不同工作区。状态栏右侧的位置最合适，不占用窗口切换的记忆负担。
4.3 针对不同工作流的模板
不同使用习惯适合不同模板。我自己常用的有三套。
第一套是“精简跑路型”，只看数量，不做详细列表：
agents 2/5 | err 0第二套是“列表跟踪型”，适合跑批量代码审查时盯每个子任务：
Subagent 2 | done 3 fail 1 | running: [demo-fixer, demo-tester]第三套是“调试输出型”，把最近完成的任务名也带上，适合开发调试新任务拆解策略时观察任务分配是否合理：
Subagent 2/5 | done 3 fail 1 | last: demo-reviewer(success)格式模板的好处是，你不用改代码就能在不同工作流之间切换。我通常会在做长任务时切换到第二套，因为能看到具体是哪个子任务卡住了。短时间的小任务则使用精简模板，减少视觉噪音。
5. 常见问题与排查经验
下面这些都是我实际使用中踩过的坑，按发生频率从高到低整理成了一张速查表。
| 现象 | 可能原因 | 解决思路 |
|---|---|---|
| tmux 状态栏一直显示空白 | 脚本执行报错但 tmux 不显示错误 | 先在终端手动执行claude_statusbar.py --once，确认输出是否正常 |
| 活跃数只增不减 | 结束事件没有匹配到启动事件 | 检查事件类型字段是否包含subagent_end，以及是否按 session 过滤 |
| 状态栏闪烁明显 | 脚本单次执行时间过长 | 降低轮询频率，关闭无关日志扫描，避免在脚本里做重活 |
| 数字明显偏大 | 多次启动脚本导致重复读取旧文件 | 检查脚本是否有持久化 offset，避免临时文件或启动时重置 |
| 中文任务名截断 | tmux 状态栏按显示宽度截断，中文字符宽一倍 | 调整status-right-length，或减少输出中的中文字符数 |
| 输出文本带多余空行 | 脚本打印了\n之外的内容 | 确保--once模式下只打印一次内容，不打印调试信息 |
active数只增不减是我最长遇到的问题。根源出在日志文件的 offset 状态没有被正确持久化：如果 tmux 每 2 秒拉起一个全新进程，而脚本每次都从文件末尾开始读，那它看不到历史启动事件，自然不知道哪些 Subagent 已经结束。解决方式是把当前统计状态保存为一个本地缓存文件，每次启动先把缓存读入，再增量处理新事件。这样即使外部脚本被频繁拉起，也能基于历史状态继续计算。
还有一个容易被忽略的点：Claude Code 的会话日志文件可能因为会话恢复而追加内容，也可能因为磁盘清理而整个消失。如果脚本打开文件时发现找不到对应文件，不要直接崩溃，而是静默重置统计状态，等下一次刷新时重新定位新文件。我在这类小工具里始终坚持一个原则：宁可状态暂时不可用，也不能让工具把宿主终端的体验拖垮。
排查时我发现，把原始 JSONL 里的事件结构先打印出来看一遍，比直接写解析逻辑节省很多时间。你可以用下面这条命令快速检查最近的 Subagent 事件类型：
tail -n 200 ~/.claude/projects/demo/latest_session.jsonl | jq -r '.type // empty' | sort | uniq -c这一步能让你立刻确认当前日志里到底有哪些事件类型，字段名是什么，再决定解析逻辑怎么写。
6. 这个工具后续还能怎么扩展
跑顺之后，我又给这个状态栏加了一些额外能力，扩展方向基本都是把同一份状态数据换成不同的出口。比如我可以把统计结果同时写进一个临时文件，再配合 tmux 的monitor-activity监测进程，实现“某个 Subagent 结束后自动发出通知”的效果，这样人离开终端也能第一时间知道任务完成的节奏。
另外，如果你平时会同时开好几个 Claude Code 会话，可以为每个会话分配一个独立状态栏模板，在状态文本里带上会话标识前缀。比如webapp:和backend:开头，方便区分当前底部的状态到底属于哪个项目。我实测下来，即使同时开三四个会话，每 2 秒刷新一次也完全不影响终端流畅度。
最后还有个很实用的技巧：不要让状态栏工具只服务 Claude Code。你可以复用同一套“读 JSONL 事件 -> 增量解析 -> 渲染到状态栏”的框架，把数据源换成其他会追加写入日志的命令行工具，比如自动化测试框架、后台构建任务、数据同步脚本等等。只要目标程序有可解析的增量日志，这套自定义状态栏就能变成你终端的通用监控面板。我的体会是，这类小工具真正的价值不在于显示了几行字，而在于它把你原本需要主动去查的信息，变成了随时抬眼就能看到的界面元素，省下来的注意力比任何花哨功能都值钱。
