Claude Code状态栏详细教程：一段提示词快速装好AI驾驶舱

Claude Code 安装完成后的默认状态是什么？一个简洁的终端，但你看不到上下文占用情况、当前运行的模型、5 小时配额剩余多少，也无法知道是否有子任务在执行。你只能盯着闪烁的光标等待反馈。

这种感觉就像一位 F1 车手坐进驾驶舱，引擎已经轰鸣，但仪表盘完全黑屏——不知道油量、转速和水温，贸然踩下油门，翻车只是时间问题。而状态栏正是你急需的那块仪表盘。

第一版状态栏脚本此前已在使用。由于近期 Claude Code 频繁更新，旧版字段和接口已有部分失效，因此我制作了第二版升级，今天一并分享给大家。

这是一个纯 Python 编写的小程序，无需安装任何额外第三方库。它会在终端底部渲染 7 段实时信息。通过本文，你将了解每段显示什么内容、数据来源、颜色含义，以及如何将它部署到你的电脑上。

本文涵盖 5 个核心要点：

1. 状态栏的安装位置及 Claude Code 的调用方式
2. 7 段输出内容的详细解读——逐段深入分析
3. 上下文进度条的颜色规则（这是最关键的功能）
4. 5 小时 / 7 天配额数据是真实值还是估算值
5. 一个值得借鉴的 50% 交接习惯——与默认阈值的差异

文末附有一条可直接复制给 Claude Code 的提示词，帮你自动完成安装。

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（仅对该项目生效）

推荐使用项目级配置——每个项目独立管理，切换项目时状态栏自动跟随。

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

安装并运行后，状态栏效果如下：

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

逐段拆解说明：

常驻 4 项（①②③⑦）+ 条件 3 项（④⑤⑥）。条件段仅当相关状态出现时才显示，不占用固定位置。

下面逐一详细说明。

① 会话名·模型·计划

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

数据来源：会话名和模型由 Claude Code 启动脚本时传入。订阅计划则是在读取 macOS 钥匙串中的令牌时一并获取——Claude Code 登录时将订阅类型存储在凭证中。

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

② 代码增删

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

数据来源：Claude Code 自身统计后传递过来。

为何有用：量化本次会话的“破坏力”——修改 50 行与修改 2000 行风险完全不同。前者使用 git 回滚成本较低，后者若未阶段性提交则如同定时埋雷。

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

显示内容：当前上下文占用百分比 + 带颜色的进度条。达到 85% 时额外显示 in:Xk cache:Xk——分别是输入 Token 和缓存 Token 的数量。

数据来源：Claude Code 自行统计后传递的百分比。

颜色规则（默认阈值）：

默认阈值为 75% 黄灯、90% 红灯。但更稳健的做法比这激进得多——下文将专门说明。

④ 5 小时 / 7 天配额

显示内容：Anthropic 订阅用户的真实配额占用百分比——5 小时滚动窗口和 7 天滚动窗口，外加重置倒计时。

数据来源：这段是整个状态栏最核心的部分。脚本执行三项操作：从 macOS 钥匙串读取登录时存储的令牌；使用该令牌调用 Anthropic 官方配额查询接口；将结果缓存 5 分钟（存放在 ~/.claude/.hud-cache/ 中），避免每秒反复发起请求。

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

如果 5 小时或 7 天配额用尽达到 100%，整段变为红色的 ⚠限额已满 {倒计时}。如果接口请求失败（例如遭遇 429 限流），这段会显示黄色的 用量⚠ 占位符。

⑤ Todo 进度

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

数据来源：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“忽略”。它并非没有读取，而是读取后难以有效利用。这是底层架构的固有特性，不存在任何补丁可以修正。唯一的解决办法就是不要让上下文进入那个危险区间。

原因二：交接成本远小于返工成本。粗略对比——

前者是确定性的低代价，后者一次翻车就前功尽弃。宁可早交接、多交接。

4. 一键复刻

如果你只想快速尝试，请直接将以下内容复制给 Claude Code：

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

Claude Code 会自动为你编写脚本、修改配置并运行测试。