Claude Code自定义状态栏：实时展示子代理运行状态

1. 为什么我要折腾一个自定义状态栏

用终端里的 AI 编程助手写代码，最让人抓狂的不是模型答得不好，而是你根本不知道它现在在干什么。尤其是当它启动子任务、并行处理多个文件的时候，终端里只有一行闪烁的光标，你只能干等着，心里没底。我最初用 Claude Code 的时候就遇到过这个问题：一个稍微复杂的重构任务，它内部会派生出好几个子代理去分别处理不同模块，但界面上完全看不出来，我甚至一度以为它卡死了，直接 Ctrl+C 中断，结果发现它其实已经改了三个文件，只是还没输出结果。

后来我发现 Claude Code 提供了一个状态栏自定义的机制，可以把当前会话的关键信息实时渲染在终端底部。这个功能说白了就是给你一个钩子，让你自己写脚本去决定状态栏显示什么内容。你可以显示当前模型、当前工作目录、Git 分支、Token 消耗量，甚至——这是最关键的——显示当前有哪些子代理正在运行、它们各自在干什么。

这个工具适合谁呢？如果你只是偶尔用 AI 助手写个简单函数，那确实没必要折腾。但如果你经常让它处理多文件重构、批量代码审查、跨模块依赖分析这类复杂任务，那一个能实时反映子代理状态的状态栏，能帮你省下大量“它到底死没死”的焦虑时间。我实测下来，配好之后整个工作流的透明度提升非常明显，你能清楚看到它在并行处理哪几个方向，哪个子代理已经完成了，哪个还在跑。

接下来我会从整体设计思路讲起，然后拆解配置细节、脚本实现、子代理状态展示的具体做法，最后把我踩过的坑和排查经验一并分享出来。内容会涉及 Shell 脚本、JSON 解析、终端转义序列这些偏底层的东西，但我会尽量用大白话解释清楚每一步在干什么。

2. 状态栏机制的整体设计与思路拆解

2.1 状态栏到底是怎么工作的

Claude Code 的状态栏本质上是一个“回调脚本”机制。它在每次界面刷新的时候，会把当前会话的上下文信息打包成一个 JSON 对象，通过标准输入传给你指定的脚本，然后把你脚本的标准输出拿过来，渲染到终端底部的状态栏区域。这个设计非常聪明，因为它把“显示什么”和“怎么获取数据”解耦了——工具负责提供数据，你负责决定展示逻辑。

理解这一点很重要，因为它意味着两件事：第一，你不需要去改 Claude Code 本身的任何代码，只需要提供一个可执行脚本；第二，你的脚本每次刷新都会被调用一次，所以脚本的执行效率直接影响状态栏的流畅度。我一开始写了个特别重的脚本，每次都要去读文件、调外部命令，结果状态栏刷新明显卡顿，后来精简到只做字符串拼接和轻量 JSON 解析，才恢复流畅。

从架构上看，整个数据流是这样的：Claude Code 主进程收集会话状态，序列化成 JSON，通过管道传给状态栏脚本，脚本处理后输出一行文本，主进程读取后渲染。这个链路里唯一需要你操心的就是脚本本身。

2.2 为什么选择脚本而不是配置文件

有人可能会问，为什么不直接提供一个配置文件让你填几个字段就完事了？我理解这个设计取舍是这样的：状态栏的需求太个性化了。有人只想知道当前模型和目录，有人想显示 Git 状态，有人想监控 Token 消耗，还有人像我一样要展示子代理的运行情况。如果做成固定配置，永远满足不了所有人的需求。而脚本方案虽然门槛高一点，但灵活性是无限的——你能想到的任何信息，只要能通过脚本获取到，就能显示出来。

我选择用 Shell 脚本来实现，原因也很实际：启动快、依赖少、在各类终端环境下兼容性好。Python 脚本虽然写起来更舒服，但每次刷新都要启动一个 Python 解释器，在状态栏这种高频调用的场景下，延迟累积起来是能感觉到的。Shell 脚本加上一些轻量工具（比如jq或者纯 Shell 的字符串处理），启动开销几乎可以忽略。

2.3 子代理状态展示的核心难点

子代理状态的展示是整个工具里最有价值但也最难搞的部分。难点在于：Claude Code 传给状态栏脚本的 JSON 里，子代理的信息结构并不是一成不变的。当没有子代理运行时，相关字段可能是空的或者不存在；当有多个子代理并行时，它是一个数组，每个元素包含子代理的标识、当前状态、正在处理的任务描述等信息。

我第一次拿到这个 JSON 的时候，直接cat出来看结构，发现字段层级比想象中深。如果不做防御性处理，脚本在字段缺失的时候就会报错，状态栏直接变成一片空白或者显示错误信息。所以脚本里必须对每个字段做存在性检查，用默认值兜底。这个经验是我调试了好几个小时才总结出来的——状态栏脚本的第一原则是“永远不能崩”，因为一旦崩了，你连它为什么崩都看不到，状态栏区域只会显示一个错误占位符。

另外，子代理的状态是动态变化的，从“启动中”到“运行中”再到“已完成”，每个阶段你想展示的信息可能不同。我的做法是在脚本里做一个简单的状态映射，把原始状态码翻译成人类可读的短标签，比如用[启动]、[运行]、[完成]这样的前缀来区分。这样一眼扫过去就能知道每个子代理处于什么阶段。

3. 核心配置细节与脚本实现要点

3.1 找到并设置状态栏脚本路径

配置的入口在 Claude Code 的设置里，你需要指定一个可执行脚本的路径。这个路径可以是绝对路径，也可以是相对于项目根目录的路径。我建议用绝对路径，因为相对路径在不同工作目录下启动时容易出问题。设置的方式通常是在配置文件里加一个字段，或者在启动参数里指定。

具体来说，你需要在配置中增加类似这样的条目：

{ "statusLine": { "type": "command", "command": "/Users/yourname/.claude/statusline.sh" } }

注意这里的command字段，它指定的是脚本的完整路径。配置好之后，重启 Claude Code 或者重新加载配置，状态栏就会开始调用你的脚本。如果配置没生效，先检查路径是否正确、脚本是否有可执行权限（chmod +x），这两个是最常见的低级错误。

提示：脚本文件不要放在项目目录里，因为项目目录可能会被 Git 管理，你的个人状态栏脚本没必要提交到仓库。放在用户主目录下的隐藏文件夹里是最稳妥的做法。

3.2 解析传入的 JSON 数据

脚本从标准输入拿到的 JSON 结构大致包含这几个关键字段：会话标识、当前模型名称、当前工作目录、Git 仓库信息、Token 使用统计，以及子代理列表。我用jq来解析，因为它处理 JSON 的语法简洁且健壮。如果你的环境里没有jq，也可以用纯 Shell 的字符串截取来做，但代码会丑很多，而且容易在特殊字符上翻车。

解析的核心逻辑是这样的：

#!/bin/bash input=$(cat) model=$(echo "$input" | jq -r '.model.display_name // "unknown"') cwd=$(echo "$input" | jq -r '.workspace.current_dir // "~"')

这里用了//操作符来做默认值兜底，意思是如果字段不存在或者为 null，就用后面的默认值。这个技巧非常实用，能避免大量条件判断。cwd我做了个处理，把用户主目录替换成~，这样状态栏不会因为路径太长而被截断。

对于子代理列表，解析方式类似，但需要遍历数组：

subagents=$(echo "$input" | jq -r '.subagents // [] | .[] | "\(.status) \(.name)"')

这行命令的意思是：取subagents字段，如果是 null 就用空数组代替，然后遍历每个元素，输出“状态 名称”的格式。注意//在这里同样起到了兜底作用，没有子代理时不会报错。

3.3 构建状态栏的输出格式

输出格式的设计直接决定了状态栏的可读性。我的原则是：信息密度要高，但不能乱。终端底部通常只有一行的高度，你得在有限的空间里塞下最关键的信息。我的布局是这样的：左边显示模型简称和工作目录，中间显示 Git 分支，右边显示子代理状态摘要。

具体实现时，我用printf来拼接字符串，用颜色转义序列来区分不同信息块。比如模型名称用青色，Git 分支用绿色，子代理运行中用黄色，完成用绿色。颜色不要用太多，三到四种就够了，多了反而眼花。

printf "\033[36m%s\033[0m | \033[32m%s\033[0m | %s" "$model" "$branch" "$subagent_summary"

这里的\033[36m是青色前景色，\033[0m是重置颜色。这些转义序列在所有主流终端里都支持，不用担心兼容性。但要注意，如果你的终端主题背景色比较特殊，某些颜色可能对比度不够，建议实际看一下效果再调整。

3.4 子代理状态的聚合展示

当有多个子代理同时运行时，状态栏空间有限，不可能把每个子代理的详细信息都列出来。我的做法是做一个聚合摘要：统计运行中、已完成、等待中的子代理数量，用类似[运行 2 | 完成 1]这样的格式展示。如果只有一个子代理在跑，就直接显示它的名称和状态。

聚合逻辑用jq的group_by可以很优雅地实现：

summary=$(echo "$input" | jq -r ' [.subagents // [] | .[] | .status] | group_by(.) | map("\(.[0]): \(length)") | join(" | ") ')

这段命令先把所有子代理的状态提取出来组成数组，然后按状态分组，统计每组的数量，最后用竖线连接。输出结果类似running: 2 | completed: 1。你可以根据自己的习惯把状态名映射成中文或者更短的标签。

注意：jq的group_by要求输入数组已经排序，不过在新版本里它会自动处理排序，所以直接写就行。如果你用的是很老的版本，可能需要在前面加一个sort。

4. 完整实操流程与关键环节实现

4.1 环境准备与依赖检查

动手之前先确认环境里有没有jq。在终端里执行which jq，如果有输出路径就说明已经装了。没有的话，根据你的系统包管理器安装即可。我用的是 macOS，通过 Homebrew 安装一条命令搞定。Linux 上用 apt 或者 yum 也很方便。

除了jq，脚本里还会用到git命令来获取分支信息。这个基本上开发环境都有，不用额外装。另外确认你的终端支持 ANSI 颜色转义序列，现在的主流终端都支持，包括系统自带的终端应用和各类第三方终端。

创建脚本文件的步骤：

mkdir -p ~/.claude touch ~/.claude/statusline.sh chmod +x ~/.claude/statusline.sh

这三条命令分别是：创建配置目录、创建脚本文件、赋予可执行权限。权限这一步千万别漏，否则 Claude Code 调用脚本时会报权限拒绝的错误，而且错误信息不一定明显。

4.2 编写完整的脚本内容

下面是我实际使用的脚本完整版本，你可以直接拿去改。我会逐段解释关键部分。

#!/bin/bash # 读取标准输入的 JSON input=$(cat) # 提取基础信息，全部带默认值兜底 model=$(echo "$input" | jq -r '.model.display_name // "Claude"') cwd=$(echo "$input" | jq -r '.workspace.current_dir // ""') cwd_short="${cwd/#$HOME/~}" # 获取 Git 分支，失败时静默处理 branch=$(git -C "$cwd" branch --show-current 2>/dev/null) if [ -n "$branch" ]; then branch_display="\033[32m${branch}\033[0m" else branch_display="\033[90mno-git\033[0m" fi # 处理子代理状态 subagent_count=$(echo "$input" | jq -r '.subagents // [] | length') if [ "$subagent_count" -gt 0 ]; then subagent_display=$(echo "$input" | jq -r ' [.subagents[] | .status] | group_by(.) | map("\(.[0]):\(length)") | join(" ") ') subagent_display="\033[33m[${subagent_display}]\033[0m" else subagent_display="" fi # 拼接输出 printf "\033[36m%s\033[0m \033[90m%s\033[0m %s %s" \ "$model" "$cwd_short" "$branch_display" "$subagent_display"

这个脚本的逻辑很直白：先拿数据，再处理 Git 分支，再处理子代理，最后拼成一行输出。每一段都有兜底处理，保证任何字段缺失都不会导致脚本崩溃。

4.3 配置生效与实时调试

脚本写好后，在 Claude Code 的配置里指向它。配置生效后，你会在终端底部看到状态栏开始显示内容。如果没显示，或者显示的内容不对，调试方法很简单：手动模拟一次调用。

echo '{"model":{"display_name":"Test"},"workspace":{"current_dir":"/tmp"},"subagents":[]}' | ~/.claude/statusline.sh

这行命令手动构造一个 JSON 输入，直接执行脚本，看输出是否符合预期。如果输出正常但状态栏不显示，那就是配置路径的问题；如果输出报错，那就是脚本本身的问题。这种分离调试的方法能帮你快速定位问题出在哪个环节。

我调试的时候还遇到过一个情况：脚本手动执行完全正常，但状态栏就是不刷新。后来发现是脚本里调用了一个需要交互式终端才能工作的命令，在非交互环境下会挂起。解决办法是把所有外部命令都加上超时保护，或者改用不依赖交互的方式获取信息。

4.4 子代理状态的实时更新验证

要验证子代理状态展示是否正常工作，你需要触发一个会产生子代理的任务。我通常用一个多文件重构的请求来测试，比如让 Claude Code 同时修改三个不同模块里的函数命名。任务启动后，观察状态栏是否出现了子代理的计数。

如果状态栏没有反映子代理的变化，先检查 JSON 里subagents字段的实际结构。你可以在脚本开头临时加一行echo "$input" > /tmp/statusline_debug.json，把每次传入的 JSON 存下来，然后去看这个文件里的实际结构。这个方法虽然笨，但极其有效，能让你看到第一手的数据长什么样。

提示：调试完成后记得把写文件的代码删掉，否则每次刷新都写一次文件，时间长了会积累大量无用数据，而且影响脚本性能。

5. 常见问题与排查技巧实录

5.1 状态栏完全不显示内容

这是最常见的问题，原因通常有三个：脚本没有可执行权限、配置路径写错了、脚本第一行缺少 shebang。排查顺序建议从简到繁：先ls -l看权限，再确认配置文件里的路径和实际路径一致，最后检查脚本第一行是不是#!/bin/bash。

还有一个隐蔽的原因：脚本输出里包含了换行符。状态栏通常只渲染第一行，如果你的printf末尾带了\n，可能导致输出被截断或者显示异常。检查方法是在脚本最后用printf而不是echo，并且不要加换行。

5.2 状态栏显示乱码或颜色异常

颜色转义序列在某些终端配置下可能不被正确解析，显示成类似\033[36m这样的原始字符。这通常是因为终端不支持 ANSI 转义，或者TERM环境变量设置有问题。解决办法是先去掉所有颜色代码，确认纯文本能正常显示，再逐步加回颜色。

另一个可能是脚本输出的字符串里包含了终端不认识的转义字符。比如从 JSON 里取出来的某些字段可能带有特殊字符，直接输出会干扰终端渲染。我的做法是对所有从 JSON 取出的字符串做一次过滤，去掉控制字符。

5.3 子代理信息显示不完整

有时候状态栏只显示了子代理的数量，但没有显示具体状态。这多半是因为jq的解析路径和实际 JSON 结构不匹配。不同版本的 Claude Code 可能在字段命名上有细微差异，你需要根据实际传入的数据来调整jq的查询路径。

我建议在脚本里加一个容错分支：先尝试用预期路径解析，如果结果为空，再尝试备用路径。这样即使字段名变了，脚本也不会完全失效。

5.4 状态栏刷新导致终端卡顿

如果状态栏刷新明显拖慢了终端响应，说明脚本执行时间太长了。用time命令测一下脚本的执行耗时，超过 100 毫秒就值得优化。优化的方向包括：减少外部命令调用次数、避免在脚本里做网络请求、把多次jq调用合并成一次。

我最初的脚本里对每个字段都单独调了一次jq，六次调用加起来耗时接近 200 毫秒。后来改成一次jq调用提取所有字段，耗时降到了 30 毫秒以内，状态栏刷新立刻流畅了。

5.5 几个我踩过的坑

第一个坑是路径里的空格。我的工作目录里有个带空格的文件夹名，脚本里没加引号，导致git -C命令解析失败。后来所有变量引用都加了双引号，问题解决。这个坑很隐蔽，因为不带空格的时候一切正常，只有特定目录下才会出问题。

第二个坑是jq版本差异。我在两台机器上用同样的脚本，一台正常一台报错，查了半天发现是jq版本不同，旧版本不支持某些语法。解决办法是尽量用最基础的jq语法，避免依赖新版本特性。

第三个坑是脚本里的git命令在非 Git 目录下会输出错误信息到标准错误，虽然我加了2>/dev/null重定向，但某些情况下错误信息还是会混入标准输出。后来改成先判断目录是否是 Git 仓库，再决定是否调用git命令，彻底解决了这个问题。

6. 进阶玩法与个性化扩展

6.1 显示 Token 消耗与成本估算

状态栏里还能展示当前会话的 Token 使用量，这对控制成本很有帮助。JSON 里通常包含输入和输出的 Token 计数，你可以把它们加起来，再乘以对应的单价，估算出当前会话的大致花费。展示格式可以是Tokens: 12.3k ($0.15)这样。

需要注意的是，单价会随模型不同而变化，你需要在脚本里维护一个简单的映射表。这个表不用很精确，给个大概的估算值就行，目的是让你对消耗有个直观感受，而不是做精确计费。

6.2 根据子代理状态改变颜色

当所有子代理都完成时，状态栏的子代理区域可以变成绿色；有子代理在运行时显示黄色；如果有子代理报错则显示红色。这种颜色反馈能让你在不仔细看文字的情况下，余光扫一眼就知道当前状态。

实现方式是在脚本里根据状态统计结果选择不同的颜色代码。逻辑不复杂，但效果很好，尤其是在你同时处理多个任务、需要快速切换注意力的时候。

6.3 把状态栏信息同步到其他工具

如果你用 tmux 或者 screen 这类终端复用工具，可以把状态栏的输出同时写到一个文件里，然后让 tmux 的状态栏去读取这个文件。这样即使 Claude Code 的窗口不在前台，你也能在 tmux 的状态栏里看到子代理的运行情况。

这个扩展需要额外配置 tmux，但思路很简单：脚本在输出到标准输出的同时，把同样的内容写到一个固定路径的文件里，tmux 那边配置一个定时刷新去读这个文件。我试过这个方案，在多窗口工作流下非常实用。

6.4 子代理完成时的提示音

如果你希望子代理全部完成时能有个听觉提醒，可以在脚本里加一个判断：当子代理数量从大于零变为零时，触发一次终端响铃。实现方式是用一个临时文件记录上一次的子代理数量，每次刷新时对比。

prev_count=$(cat /tmp/claude_subagent_count 2>/dev/null || echo 0) if [ "$prev_count" -gt 0 ] && [ "$subagent_count" -eq 0 ]; then printf "\a" fi echo "$subagent_count" > /tmp/claude_subagent_count

这里的\a是终端响铃字符。这个功能在跑长任务的时候特别有用，你可以去干别的事，听到响铃再回来看结果。不过要注意别在安静的环境里被吓到，响铃音量取决于你的终端设置。

6.5 多项目切换时的状态隔离

如果你同时在多个项目里使用 Claude Code，状态栏脚本需要能正确反映当前项目的信息。由于脚本每次都会收到当前工作目录，你只需要确保所有路径相关的操作都基于这个目录来做，而不是基于脚本所在目录。这一点在写脚本的时候要特别注意，git命令一定要用-C参数指定目录，不要依赖当前工作目录。

另外，临时文件（比如记录子代理数量的那个文件）最好也按项目区分，否则多个项目之间会互相干扰。可以用工作目录的哈希值作为文件名后缀，简单有效。

7. 一些实操心得

这个状态栏工具我从最初的一个简单模型名称显示，逐步迭代到现在能完整展示子代理状态，前后改了大概七八个版本。最大的体会是：状态栏脚本的健壮性比功能性更重要。一个功能简陋但永不崩溃的状态栏，远比一个功能丰富但时不时报错的状态栏有用。因为状态栏一旦出错，你不仅失去了信息，还会被错误信息干扰，反而影响工作节奏。

另一个心得是不要过度设计。我一开始想在里面显示各种花哨的信息，结果状态栏变得又长又乱，关键信息反而被淹没了。后来做减法，只保留模型、目录、分支、子代理状态这四项，清爽了很多。状态栏的本质是“余光可见的仪表盘”，不是“信息展示中心”，克制很重要。

最后说一个实际效果：配好子代理状态展示之后，我对 Claude Code 的信任度明显提高了。以前它跑长任务的时候我总忍不住去打断看看进度，现在状态栏实时显示着每个子代理在干什么，我可以放心地去处理其他事情，等它跑完再回来看结果。这个心理上的变化，比任何技术指标都更能说明这个工具的价值。