Claude Code 自定义状态栏:实时盯住上下文用量、成本与 Git

本文是对官方文档 Customize your status line 的中文要点整理,字段与配置以原文为准。

状态栏是什么

状态栏是 Claude Code 底部一行可自定义的栏,运行你配置的任意 shell 脚本:它通过 stdin 收到 JSON 会话数据,把脚本打印的内容显示出来,给你一个常驻的、一眼可见的上下文用量 / 成本 / git 状态视图。它渲染在内置 footer 徽章上方一行,不替换它们。

适合:想边干边盯上下文用量、追踪会话成本、区分多个会话、常驻显示 git 分支与状态。

最快:/statusline 一键生成

/statusline 命令接受自然语言,Claude Code 会在 ~/.claude/ 生成脚本并自动更新设置:

/statusline show model name and context percentage with a progress bar

删除则 /statusline delete / clear / remove it,或手动删掉设置里的 statusLine 字段。

手动配置

在用户设置 ~/.claude/settings.json(或项目设置)加 statusLine 字段,type 设 "command",command 指向脚本或内联命令:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 2
  }
}

command 在 shell 里执行,也可直接内联。下面用 jq 解析 stdin 的 JSON,显示模型名与上下文百分比:

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\(.model.display_name)] \(.context_window.used_percentage // 0)% context\"'"
  }
}

padding(可选,默认 0)控制额外的横向缩进字符数。

stdin 里能拿到哪些字段

Claude Code 把 JSON 通过 stdin 传给你的脚本,常用字段:

• 模型:model.id、model.display_name
• 工作区:workspace.current_dir(=cwd)、workspace.project_dir、workspace.added_dirs、workspace.git_worktree、workspace.repo.host/owner/name
• 成本:cost.total_cost_usd(客户端估算)、cost.total_duration_ms、cost.total_lines_added / total_lines_removed
• 上下文:context_window.total_input_tokens / total_output_tokens、context_window.context_window_size(默认 200000,扩展上下文 1000000)、context_window.used_percentage / remaining_percentage

小贴士

• 支持多行状态栏(如第一行 git 信息、第二行带色的上下文进度条)。
• 脚本里读不到终端宽度(tput cols 不行);改读环境变量 COLUMNS / LINES(Claude Code v2.1.153+ 会在运行前设置)。