太长不看版
- /statusline 是 Claude Code 的内置斜杠命令。跑一次、用一句话描述你想要的状态栏，statusline-setup 代理就会写好脚本，并把 statusLine 配置块写进 ~/.claude/settings.json。
- Windows 上代理会给三条路：转换你的 PowerShell 配置文件、指向 WSL 或 Git Bash 配置，或者直接建一个显示用户名、目录、模型和上下文用量的默认版。
- 脚本从标准输入（stdin）读一份 JSON：model.display_name、workspace.current_dir、context_window.used_percentage、cost.total_cost_usd 等字段随取随用；echo 出什么状态栏就显示什么，还支持 ANSI 颜色和多行。
- 全程本地运行、不烧 token。默认跟着会话事件刷新（也可用 refreshInterval 定时刷新），不想用了就 /statusline clear 一键清掉。
How to Set Up a Custom Status Line in Claude Code CLI to Track API Costs and Context Usage (2026)
频道:ProgrammingKnowledge23:32
Claude Code最該裝的不是Skill，是這個腳本｜彩色進度條、費用、git 分支一眼看完
频道:YAHA學堂8:44
Your Claude Code Terminal Should Look Like This (Status Line Setup)
频道:Leon van Zyl9:02
How to Add a Custom Status Line in Claude Code on Windows 11 (Project-Level Setup)
频道:Devtamin7:27
Status line — Claude Code documentation
官方文档:code.claude.com
第 1–4 步录制于 Windows PowerShell，第 5–12 步录制于 macOS；截图只取自干净的纯录屏——带主播摄像头或烧录标注的画面一律没有采用。
「声明操作系统、脚本放全局并单独成文件、需要 jq、调试文件法」等技巧来自上面另外两期视频；深度小节里的字段名与刷新行为以官方 statusline 文档为准。
/statusline 图文教程（12 步）
跑 /statusline，让 Claude 帮你接好
- 1
在终端里启动 Claude Code
在 PowerShell、Terminal 或任意终端里输入 claude 启动。新会话只有欢迎框和空输入行——输入框下方那条状态栏的位置还空着，要等 statusLine 配置块写进 ~/.claude/settings.json 之后才会出现。
Windows PowerShell 里的 Claude Code v2.1.83 新会话：欢迎框、空输入行，状态栏还没有。在 0:22 观看 - 2
输入 /statusline 命令
斜杠命令菜单里写得很直白：设置 Claude Code 的状态栏 UI。回车即可。这个内置命令认识自然语言，不需要你手写脚本——当然，它生成的脚本之后随你改。
自动补全把 /statusline 标注为「设置 Claude Code 状态栏 UI」的命令。在 0:32 观看 - 3
回答 setup 代理的问题
一个专门的 statusline-setup 代理接管后续。Windows 上它会提示找不到标准 shell 配置文件，然后给三条路：贴出你的 PS1 配置文件让它转换、指向 WSL 或 Git Bash 配置，或者直接建一个默认版（显示用户名、目录、模型、上下文用量）。三条路最后都落在同一个 settings.json 配置块上。
Windows 三选项：转换 PS1、指向自定义配置，或者从合理的默认开始。在 1:20 观看 - 4
确认它写好的配置和脚本
代理跑完会先打印一条状态栏预览——用户名、目录、git 分支、模型、上下文百分比——并告诉你文件落在哪：配置在 ~/.claude/settings.json，脚本在 ~/.claude/statusline-command.sh。macOS 和 Linux 流程相同，Claude 还可以直接把你现有的 .zshrc 或 .bashrc 提示符转换成状态栏。
配置完成：预览 hardik | ~/Dev/project | main | Claude Opus 4.6 | ctx:42%，并给出两个文件路径。在 3:06 观看
用一句自然语言描述你想要的状态栏
- 5
用一句话点名你要的数据
随时再跑一次 /statusline，用一句话描述需求，例如：显示模型名和上下文百分比，带进度条。其他语言也行——这条命令本质就是给代理的提示词。新请求会重写同一个脚本，不会越堆越多。
一句自然语言——模型名加上下文百分比进度条——就是全部接口。在 1:07 观看 - 6
看 statusline-setup 工具干活
Claude Code 会调用内置的 statusline-setup 工具，先读当前的 ~/.claude/settings.json 和状态栏脚本，再重写。Claude 自己的悬浮卡片把功能总结得很到位：配置一个自定义状态栏，监控上下文窗口用量、花费和 git 状态。
statusline-setup 工具运行中：读取配置和脚本，悬浮卡片写明功能说明。在 1:12 观看 - 7
认识你的新状态栏
跑完后代理会复述设计——模型名亮青色，二十字符宽的上下文进度条，49% 以内绿色、50% 起黄色、80% 起红色——而且状态栏已经出现在终端底部，不用重启会话，不满意当场继续改。
代理的复述上方，实时状态栏显示 Opus 4.6 (1M context)、上下文 2%。在 1:27 观看
读懂它生成的脚本
- 8
一份 JSON 从标准输入进来
打开生成的脚本——macOS/Linux 上是 ~/.claude/statusline.sh，Windows 上是 statusline-command.sh 或 .ps1。每次刷新，Claude Code 都会把会话的 JSON 快照通过标准输入喂给脚本。生成的 Bash 用 jq 取字段：.model.display_name、.workspace.current_dir、.cost.total_cost_usd、.cost.total_duration_ms 和 .context_window.used_percentage。
解析段：五个 jq 读取，再按 90% 和 70% 的上下文阈值选 BAR_COLOR。在 5:46 观看 - 9
echo 什么，状态栏就显示什么
脚本尾部全是展示逻辑：printf 格式化花费、毫秒换算成分秒、每个 echo 对应一行状态栏——第一行模型加目录加 git 分支，第二行进度条、百分比、花费和计时。可以放心用 ANSI 颜色转义，多写一个 echo 就多一行。
两行 echo 两行状态栏：模型＋目录＋分支，以及进度条＋百分比＋花费＋计时。在 6:13 观看 - 10
用同样的思路加 git 信息
git 数据就是一次子进程调用：git rev-parse --git-dir 判断是否在仓库里，git branch --show-current 取分支名，git diff --cached --numstat 和 --numstat 统计暂存与已修改文件数。生成示例会把暂存数标绿、修改数标黄——如果你同时开好几个 Claude Code 会话跨分支干活，这个小护栏很救命。
GIT_STATUS 由暂存数和修改数拼成，用 ANSI 颜色标绿标黄。在 5:01 观看
配置块归你管：清除、重写、上多行
- 11
一切都在 settings.json 的一个配置块里
翻开 ~/.claude/settings.json，整个功能就是一个 statusLine 对象：type 为 command，command 指向要跑的脚本——本次演示里是 bash ~/.claude/statusline-command.sh。跑 /statusline clear 代理就会删掉这个块；再描述一个新状态栏它又重写。想要仓库级状态栏，也可以放进项目里的 .claude/settings.json。
/statusline clear 的 diff：statusLine 配置块被移出 settings.json，随时可以重写。在 1:41 观看 - 12
进阶：多行显示花费、时长和仓库链接
状态栏可以叠多行，所以官方文档的多行示例先打印一个可点击的仓库链接（OSC 8 转义序列），第二行再放上下文进度条、用 printf '$%.2f' 格式化的会话花费和已用分秒。阈值配色、限额百分比、vim 模式——想要什么组合直接开口，改到满意为止。
带注释的示例：第一行 OSC 8 仓库链接；第二行进度条、花费和时长。在 7:31 观看
你的 statusline 脚本会收到哪些 stdin 字段
Claude Code 调用脚本时，会把会话的 JSON 快照放到标准输入里。以下是最值得知道的字段（以官方文档为准）——把它们写进 /statusline 的一句话里，代理就会帮你接上：
- 1会话基础：session_id、transcript_path、cwd、version；发出第一条提示后还有 session_name 和 prompt_id。
- 2model.id 与 model.display_name——当前模型，状态栏最常用的开头。
- 3workspace.current_dir、workspace.project_dir、workspace.added_dirs；目录属于托管仓库时还有 workspace.git_worktree 和 repo.owner / repo.name。
- 4context_window.used_percentage 与 remaining_percentage——used 只统计输入、缓存写入和缓存读取 token，不含输出。
- 5context_window.current_usage 进一步拆成 input_tokens、output_tokens、cache_creation_input_tokens、cache_read_input_tokens；首次 API 调用前和 /compact 后为 null。
- 6cost.total_cost_usd、cost.total_duration_ms、cost.total_api_duration_ms、cost.total_lines_added、cost.total_lines_removed——做花费与节奏型状态栏用。
- 7Pro/Max 订阅有 rate_limits.five_hour 和 rate_limits.seven_day（含 used_percentage 与 resets_at）；网关接入则是 spend_limit 一对。每个窗口都可能单独缺省，记得兜底。
- 8还有一批杂项：exceeds_200k_tokens、fast_mode、effort.level、thinking.enabled、output_style.name、vim.mode、agent.name、pr.number / pr.url / pr.review_state 和 worktree.* 系列。
以上字段名以官方 statusline 文档为准，文档里还附带 Bash、Python、Node.js 现成脚本、Windows PowerShell 版本，以及慢机器用的 git 缓存方案。
排错：状态栏不显示、数字不对、刷新不及时
状态栏的故障基本逃不出下面五种，全部可以在当前会话里修好，不用重装。
- 1完全不显示——先检查 ~/.claude/settings.json 的 JSON 是否写坏；录屏里就有一次因为命令路径里多打了字符，状态栏一直没出现，改完重启会话才恢复。另外权限弹窗打开时状态栏会暂时隐藏，工作区未信任时脚本也不会运行。
- 2空白且无报错——脚本以非零状态退出或什么都没打印。手动跑一下，例如 echo '{"model":{"display_name":"Opus"}}' | bash ~/.claude/statusline.sh，看输出；claude --debug 也会记录脚本 stderr。
- 3只在某个项目里出现——配置块写进了项目级 .claude/settings.json。挪到 ~/.claude/settings.json 就是全局状态栏。
- 4数字明显不对——脚本多半取错了字段。让 Claude 把原始 stdin JSON 转存到调试文件里，读那个文件再改字段；录屏里的 macOS 会话就是这么自己修好百分比的。
- 5macOS/Linux 上脚本在但渲染不出来——多半是没装 jq。先装（brew install jq、sudo apt install jq 或 Windows 等价方式），再让 Claude 更新一次状态栏。
状态栏多久刷新一次（要花钱吗）
脚本在会话开始时跑一次，之后跟着事件走：新的助手消息、/compact 完成、权限模式或 vim 模式切换、command 本身被修改、限额窗口重置、热的提示缓存到期。刷新有 300 毫秒防抖，上一次还没跑完又来新任务时，旧任务会被取消。
因为按事件驱动，空闲时状态栏会安静下来——比如等一个长时间的子代理任务。想让时间类数据持续走动，就给 statusLine 块加 refreshInterval（单位秒）。这一切都不碰 API：脚本本地运行，不消耗任何 token；多写几行 echo 就是多几行状态栏。
还有两个进阶开关：hideVimModeIndicator 可以隐藏内置的 -- INSERT -- 提示（适合自己渲染 vim 模式的脚本）；subagentStatusLine 则给子代理在代理面板里单独配置状态行。