Status Line 自定义状态栏

是什么

status line 是 Claude Code 底部的可自定义状态栏，运行任意 shell 脚本，通过 stdin 接收 JSON session 数据，显示脚本输出的内容。适合持续监控 context 用量、成本、git 状态等信息。

核心机制

配置方式

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

快速生成

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

Claude Code 生成脚本文件并自动更新 settings。

内联命令示例

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

可用数据字段（JSON stdin）

字段	说明
model.display_name	当前模型名称
context_window.used_percentage	context 使用百分比
context_window.used_tokens	已用 token 数
context_window.max_tokens	最大 token 数
session.cost_usd	当前 session 估算成本
session.duration_seconds	session 持续时间
git.branch	当前 git 分支
git.status	git 状态
vim.mode	Vim 模式（INSERT/NORMAL 等）

触发时机

• 每次 Claude Code 状态变化时（事件驱动）
• 设置 refreshInterval 后额外按时间间隔触发（最小 1 秒）

关键细节

• padding 字段添加额外水平间距（字符数），是相对缩进而非绝对距离
• hideVimModeIndicator: true：脚本自己渲染 vim.mode 时隐藏内置的 -- INSERT -- 文字
• refreshInterval 适合显示时钟或 subagent 改变 git 状态时的场景
• 禁用：/statusline delete 或手动删除 settings 中的 statusLine 字段

与其他概念的关联

• settings - statusLine 配置在 settings.json 中的位置
• fullscreen - 全屏模式下 status line 的显示效果

实践要点

• 脚本从 stdin 读取 JSON，用 jq 解析最方便
• context 用量接近上限时用颜色编码（ANSI 转义码）提醒
• 多行 status line：脚本输出多行文本即可
• subagent 运行时 git 状态可能变化，设置 refreshInterval 保持同步