Claude Code 状态栏完整教程：一段提示词装好你的 AI 驾驶舱

Q: 会话名·模型·计划？

显示什么：当前会话名、使用的模型（Opus 4.6 / Sonnet 4.6 / Haiku 4.5 之一）、订阅计划（Max 或 Pro）。 数据从哪来：会话名和模型是 Claude Code 启动脚本时传进来的。订阅计划是脚本在读取 macOS 钥匙串里的令牌时顺带读到的——Claude Code 登录时把订阅类型一起存在了凭证里。 颜色：会话名霓虹青，模型霓虹粉，Max 橙色，Pro 紫色。

Q: 上下文进度条（全车灵魂）？

显示什么：当前上下文占用百分比 + 带颜色的进度条。达到 85% 时额外显示 in:Xk cache:Xk——分别是输入 Token（令牌，可以理解为 AI 的"字数单位"）和缓存 Token 的数量。 数据从哪来：Claude Code 自己统计后传过来的百分比。 颜色规则（代码里默认的阈值）： | 百分比 | 颜色 | |--------|------| | 0 – 74% | 🟢 绿 | | 75 – 89% | 🟡 黄 | | 90 – 100% | 🔴 红 | 翔宇的个人工作习惯比这更激进——下一节专门讲。

Q: 5 小时 / 7 天配额？

显示什么：Anthropic 订阅用户的真实配额占用百分比——5 小时滚动窗口（rolling window，意思是"过去 5 小时内的累计用量"）和 7 天滚动窗口，外加重置倒计时。 数据从哪来：这段是整个状态栏最硬核的部分。脚本做了三件事： 1. 从 macOS 钥匙串（Keychain，苹果系统用来存密码的安全仓库）里读取你登录 Claude Code 时存的令牌 2. 拿这个令牌去调 Anthropic 官方的配额查询接口 3. 把结果缓存 5 分钟（存在 ~/.claude/.hud-cache/ 里），避免每秒都在发请求 颜色规则（冷色系，故意和上下文的暖色系区分开）： | 百分比 | 颜色 | |--------|------| | 0 – 49% | 🔵 蓝 | | 50 – 79% | 🟣 紫 | | 80 – 100% | 🌸 粉 | 如果 5 小时或 7 天打满 100%，整段变成红色的 ⚠限额已满 {倒计时}。 如果接口请求失败（比如被 429 限流——访问太频繁被官方临时挡一会儿），这段会显示黄色的 用量⚠ 占位。

Q: Todo 进度？

显示什么：当前会话的待办任务进度。三种形态： | 状态 | 显示 | |------|------| | 全部完成 | ✓ 3/3 绿色勾 | | 有任务进行中 | ▸任务名 1/3 黄色箭头 + 任务简名 | | 有任务待做但没开始 | ☐ 0/3 灰色方框 | 数据从哪来：Claude Code 会把每轮对话写到一个日志文件里（后缀 .jsonl，每行一条消息）。脚本从这个文件的尾部 64KB 开始往回扫描，找到 Claude 用过的 TaskCreate（创建任务）/ TaskUpdate（更新任务）/ TodoWrite（写待办）这些工具调用，拼出当前进度。 为什么只读尾部 64KB？因为一个长会话的日志文件可能好几 MB，扫全文不经济。尾部 64KB 足够覆盖当前活跃任务。

Q: 子 Agent（子助手）？

显示什么：当前正在运行的子助手，格式 ⚡code-reviewer 审查认证模块。橙色。 这里的"子 Agent"指的是你让 Claude 派出去做专项工作的小助手——比如让它派一个 code-reviewer（代码审查员）去审查某段代码，或者派一个 researcher（研究员）去查资料。 数据从哪来：同样从对话日志文件里解析——扫描 Agent 工具的启动和返回，判断哪些子助手还在跑。状态栏只显示"运行中"的，最多 2 个。 另外还有一种特殊情况——如果你当前就在一个子 Agent 会话里（Claude Code 会在传给脚本的 JSON 里放一个 agent.name 字段），那这段会显示你所在的那个子助手名。

Claude Code 装完默认是空终端——上下文（也就是 AI 这次对话能"记住"的内容容量）用了多少、在跑哪个模型、5 小时配额还剩多少、有没有子任务在跑，一项都看不见。

打个比方——Claude Code 就是一辆 F1，引擎很猛，但默认连仪表盘都没打开。看不见油量、看不见转速、看不见水温，一脚油门踩到底，不翻车才怪。状态栏就是那块仪表盘。

翔宇之前发过这套状态栏脚本的第一版。最近 Claude Code 连着更新，原来的字段和接口有些对不上了，顺手做了第二版升级，今天一并公开。

这是一个纯 Python 写的小程序，不需要额外安装任何库，会在终端底部渲染 7 段实时信息。

跟着读完，你会知道每一段显示的是什么、数据从哪来、颜色代表什么、怎么在自己电脑上装上。

这篇文章讲 5 件事

状态栏装在哪、Claude Code 怎么调用它
7 段输出的含义——一段一段讲透
上下文进度条的颜色规则（这块是灵魂）
5 小时 / 7 天配额的数据是真的还是估算的
翔宇自己的 50% 交接习惯——和源码默认阈值的区别

文末附一句可以直接丢给 Claude Code 自动装好的提示词。

💡 划重点

本教程的状态栏脚本是项目级配置（Project-level，即只对当前项目生效），不是全局配置。每个项目在自己的 .claude/settings.json 里指向项目内的脚本，切项目自动切状态栏。

1. 状态栏装在哪

Claude Code 原生支持 statusLine（状态栏）这个配置项（近期版本都有，官方文档见 code.claude.com/docs/en/statusline）。

工作方式很简单——Claude Code 会定期运行你指定的小程序，把当前会话的状态（打包成 JSON 这种文本格式）喂给它。你的程序只要把想显示的内容打印一行出来，Claude Code 就会把这行渲染到终端底部。

刷新节流是 300 毫秒（不会每秒刷几十次拖垮性能），只取你脚本 stdout（标准输出）的第一行作为状态栏内容。

所以状态栏本质上就是一个读 JSON、打印一行文本的普通脚本。

翔宇这份用的是 Python，单文件，不需要安装任何第三方库，直接用 macOS 系统自带的 python3 就能跑。

配置文件位置：

全局配置：~/.claude/settings.json（对所有项目生效）
项目配置：<你的项目>/.claude/settings.json（只对这个项目生效）

翔宇推荐项目级配置——每个项目自己管自己，切项目时状态栏自动跟随。

💬 通俗讲

Claude Code 每隔一小段时间，就会敲一下你这个脚本的门，问："帮翔宇画一行状态栏出来。"
脚本打印什么，终端底下就显示什么。
没多复杂。

2. 7 段输出——每一段显示什么

装完跑起来，状态栏长这样：

会话·Opus 4.6 Max ┊ +42 -7 ┊ ████░░░░ 29% ┊ 5h ░░░░░░ 6% 4h16m ┊ ▸任务 1/3 ┊ ⚡agent ┊ v2.1

翔宇一段一段拆：

#	段名	显示内容	常驻/条件
①	会话名·模型·计划	当前会话名、使用的模型、订阅计划（Max / Pro）	常驻
②	代码增删	本次会话累计增加/删除行数（+42 -7）	常驻
③	上下文进度条	上下文占用百分比 + 带色进度条	常驻
④	5h / 7d 配额	Anthropic 订阅的滚动配额真实占用	订阅用户
⑤	Todo 进度	当前待办任务进度（完成几个/共几个）	有任务时
⑥	子 Agent（子助手）	正在运行的子助手类型和描述	有子助手时
⑦	版本	Claude Code 版本号	常驻

常驻 4 个（①②③⑦）+ 条件 3 个（④⑤⑥）。条件段只在相关状态出现时才显示，不占位。

下面挨个讲清楚。

① 会话名·模型·计划

显示什么：当前会话名、使用的模型（Opus 4.6 / Sonnet 4.6 / Haiku 4.5 之一）、订阅计划（Max 或 Pro）。

数据从哪来：会话名和模型是 Claude Code 启动脚本时传进来的。订阅计划是脚本在读取 macOS 钥匙串里的令牌时顺带读到的——Claude Code 登录时把订阅类型一起存在了凭证里。

颜色：会话名霓虹青，模型霓虹粉，Max 橙色，Pro 紫色。

★ 翔宇的建议

不同任务绑不同模型。翔宇的习惯——
架构、重构、疑难调试 → Opus
日常编码、文档、代码审查 → Sonnet
格式转换、简单查询 → Haiku

状态栏一直显示当前模型，是为了防止你随手切换（用 /model 命令）还没发现，白烧钱。

② 代码增删

显示什么：本次会话累计增加 / 删除的代码行数，格式 +342 -87。

数据从哪来：Claude Code 自己统计后传过来的。

为什么有用：量化本次会话的"破坏力"。改了 50 行和改了 2000 行是完全不同的风险级别——前者 git（版本管理工具）回滚成本低，后者没有阶段性提交（checkpoint commit，意思是"在半路存一次档"）就是定时埋雷。

③ 上下文进度条（全车灵魂）

显示什么：当前上下文占用百分比 + 带颜色的进度条。达到 85% 时额外显示 in:Xk cache:Xk——分别是输入 Token（令牌，可以理解为 AI 的"字数单位"）和缓存 Token 的数量。

数据从哪来：Claude Code 自己统计后传过来的百分比。

颜色规则（代码里默认的阈值）：

百分比	颜色
0 – 74%	🟢 绿
75 – 89%	🟡 黄
90 – 100%	🔴 红

翔宇的个人工作习惯比这更激进——下一节专门讲。

④ 5 小时 / 7 天配额

显示什么：Anthropic 订阅用户的真实配额占用百分比——5 小时滚动窗口（rolling window，意思是"过去 5 小时内的累计用量"）和 7 天滚动窗口，外加重置倒计时。

数据从哪来：这段是整个状态栏最硬核的部分。脚本做了三件事：

从 macOS 钥匙串（Keychain，苹果系统用来存密码的安全仓库）里读取你登录 Claude Code 时存的令牌
拿这个令牌去调 Anthropic 官方的配额查询接口
把结果缓存 5 分钟（存在 ~/.claude/.hud-cache/ 里），避免每秒都在发请求

颜色规则（冷色系，故意和上下文的暖色系区分开）：

百分比	颜色
0 – 49%	🔵 蓝
50 – 79%	🟣 紫
80 – 100%	🌸 粉

如果 5 小时或 7 天打满 100%，整段变成红色的 ⚠限额已满 {倒计时}。
如果接口请求失败（比如被 429 限流——访问太频繁被官方临时挡一会儿），这段会显示黄色的 用量⚠ 占位。

⚠️ 重要提示

这段只在 macOS 上能看到——脚本的钥匙串读取只实现了苹果系统那一套，Linux / Windows 用户跑这份脚本不会显示配额段。
此外，按 API Key（接口密钥，即按用量付费的开发者账号）计费的用户也没这段，属正常。企业版（Enterprise）接口不返回数据也看不到。
如果你设置了中转 API（把请求转到非官方服务器），这段也会自动跳过——因为中转 API 没有配额查询这个接口。

⑤ Todo 进度

显示什么：当前会话的待办任务进度。三种形态：

状态	显示
全部完成	`✓ 3/3` 绿色勾
有任务进行中	`▸任务名 1/3` 黄色箭头 + 任务简名
有任务待做但没开始	`☐ 0/3` 灰色方框

数据从哪来：Claude Code 会把每轮对话写到一个日志文件里（后缀 .jsonl，每行一条消息）。脚本从这个文件的尾部 64KB 开始往回扫描，找到 Claude 用过的 TaskCreate（创建任务）/ TaskUpdate（更新任务）/ TodoWrite（写待办）这些工具调用，拼出当前进度。

为什么只读尾部 64KB？因为一个长会话的日志文件可能好几 MB，扫全文不经济。尾部 64KB 足够覆盖当前活跃任务。

⑥ 子 Agent（子助手）

显示什么：当前正在运行的子助手，格式 ⚡code-reviewer 审查认证模块。橙色。

这里的"子 Agent"指的是你让 Claude 派出去做专项工作的小助手——比如让它派一个 code-reviewer（代码审查员）去审查某段代码，或者派一个 researcher（研究员）去查资料。

数据从哪来：同样从对话日志文件里解析——扫描 Agent 工具的启动和返回，判断哪些子助手还在跑。状态栏只显示"运行中"的，最多 2 个。

另外还有一种特殊情况——如果你当前就在一个子 Agent 会话里（Claude Code 会在传给脚本的 JSON 里放一个 agent.name 字段），那这段会显示你所在的那个子助手名。

⑦ 版本

显示什么：Claude Code 版本号，比如 v2.1.59。暗灰色。

为什么有用：Claude Code 更新很快，某些功能在不同版本行为会变。显示版本让你在报问题或查文档时，第一时间对得上号。

3. 上下文 50%：翔宇的个人交接铁律

源码默认的颜色阈值是 75% 变黄 / 90% 变红。但翔宇自己用的时候比这激进得多——上下文用到 50% 就主动交接（把当前会话的进度总结一份，粘到新会话继续做）。

为什么是 50%，不等 75% 黄灯？

两个原因。

原因一：中间遗忘现象（Lost in the Middle）。

这是 2024 年一篇真实论文（Liu 等人，发表在 TACL 期刊）证明的现象——上下文越长，AI 对中间段信息的提取能力越弱于开头和结尾。

说人话——你早期给 Claude 讲的关键约束、业务规则、文件结构，到了后半段可能被 AI"视而不见"。它不是没读到，是读到了但用不上。

这是底层架构的固有特性，没有补丁可打。唯一的解法就是别让上下文走到那个区间。

原因二：交接成本 < 返工成本。

翔宇粗略对比——

选择	大致代价
50% 主动交接	5 分钟写摘要 + 开新会话
等到 80-90% 翻车后回滚	可能整晚代码白干 + 第二天重写

前者是确定性的小代价，后者一次翻车就翻本。翔宇宁可早交接、多交接。

📌 记住这点

这是翔宇的个人工作习惯，不是脚本硬性要求。
脚本默认告警是 75% 黄 / 90% 红。
想跟翔宇一样激进，直接让 Claude 帮你改脚本里的阈值即可（在下一节的一键提示词里告诉它就行）；想用默认，什么都不改也正常。

4. 一键复刻

如果你只想试试看，把下面这段直接丢给 Claude Code：

「我想给我的 Claude Code 装一个状态栏。希望能在终端底部显示：当前用的是哪个模型、上下文用了百分之多少（到 50% 提醒我交接）、这次会话改了多少行代码、订阅配额还剩多少。帮我用 Python 写一个脚本放到 ~/.claude/ 下，然后配置到 settings.json 里。」

Claude Code 自己会帮你写脚本、改配置、跑测试。翔宇这份生产级的完整版本——带分色阈值、钥匙串读取、官方接口缓存、防崩溃兜底——放在《AI 编程实操课》里，一段提示词就能全自动部署。

这套状态栏只是「翔宇工作流 AI 编程实操课」的一个实用工具。在课程中，你还会学到 Claude Code Skill 开发入门、OpenClaw 多 Agent 编排、Syncthing 多设备配置同步、Hermes Agent 知识库实战等一整套体系。