它到底是什么

/statusline 是 Claude Code 会话内的 slash 命令,接受自然语言描述作为参数。执行后,Claude Code 会自动生成一个 shell 脚本并更新 settings.json,在终端底部渲染一条可持续刷新的状态行(status line)。

状态行的本质是:Claude Code 将会话 JSON 数据通过 stdin 传给你指定的脚本,脚本把想显示的内容输出到 stdout,底部状态栏就显示该内容。这是一个纯本地机制,不依赖任何云端服务。

怎么触发 / 怎么使用

1. 用自然语言生成配置(推荐)

在会话内直接输入:

/statusline <你想显示的内容描述>

Claude Code 会读懂意图,生成脚本文件并写入 settings.json。

示例:

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

/statusline show the model name in orange

/statusline
Show model, current directory, git branch, context percentage, and estimated cost.
Keep it one line and handle missing fields.

/statusline 接受自然语言指令,描述你想显示的内容,Claude Code 会据此在 ~/.claude/ 生成脚本并自动更新 settings(官方文档未记录"不加参数复现终端 prompt"这类默认行为)。

2. 手动配置 settings.json

跳过 /statusline 命令,直接编辑配置文件:

用户级(全局生效): ~/.claude/settings.json 项目级: .claude/settings.json

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "refreshInterval": 5
  }
}

3. 脚本接收的 stdin JSON 数据

Claude Code 每次刷新时将如下结构的 JSON 通过 stdin 传入脚本:

注意: 并非每个字段都会在每个账户、版本或路由下出现,脚本必须做防御性字段缺失处理。

一个最小 bash 示例(依赖 jq):

#!/usr/bin/env bash
data=$(cat)
model=$(echo "$data" | jq -r '.model.display_name // "unknown"')
pct=$(echo "$data" | jq -r '.context_window.percentage // "?"')
echo "${model} | ctx: ${pct}%"

4. 多行状态栏

脚本输出多行文本即可显示多行状态栏:

#!/usr/bin/env bash
data=$(cat)
branch=$(echo "$data" | jq -r '.git.branch // ""')
pct=$(echo "$data"   | jq -r '.context_window.percentage // "?"')
cost=$(echo "$data"  | jq -r '.cost.total_cost_usd // 0')
echo "${branch}"
printf "ctx: %s%%  cost: \$%.4f\n" "$pct" "$cost"

5. ANSI 颜色

ANSI 转义码可以正常工作;OSC 8 超链接取决于终端是否支持,建议先用纯文本测试,再按需添加颜色。

运行约束 / 限制

跟同类"底部/外观"原语对比

/statusline 改的是终端底部信息行,容易和改配色的 /theme、改输出格式的命令混淆。它们各管一处:

记忆法:底部那一行用 /statusline,颜色用 /theme,回答的口吻/结构用 /output-style。三者互不冲突,可叠加使用。statusLine 脚本纯本地执行,不依赖云端。

经典使用场景

• 监控上下文用量:用进度条实时显示 context window 消耗百分比,提前感知接近上限
• 追踪会话成本:显示累计 USD 花费,便于预算管控
• 常驻 git 状态:永远可见当前分支名和脏文件状态,无需手动 git status
• 区分多个并发会话:显示 session 或 worktree 信息,避免在多窗口间混淆

常见坑

1. jq 未安装导致脚本无声失败:bash 脚本依赖 jq 解析 stdin JSON。如果 jq 不存在,脚本会静默退出,状态行显示为空白。解决:先 brew install jq 或 apt install jq,或改用 Python/Node.js 脚本。
2. 修改 settings.json 后需要重启 Claude Code 才能生效:配置变更不会热重载。
3. 字段缺失导致脚本崩溃:部分字段(如 rate_limits、git.branch)不会在所有环境下出现。未做 null 防护的脚本会出错。始终使用 jq -r '.field // "default"' 形式。
4. OSC 8 超链接在部分终端不受支持(据通用终端经验,官方未在 statusline 上下文专门记录):若状态行出现乱码,先去掉非标准 ANSI 序列,只保留标准颜色转义。

来源

• Customize your status line — Claude Code Docs (code.claude.com)
• How to Customize Your Claude Code Status Line — alexop.dev
• Claude Code Statusline: Routes, Fields, Scripts, and Fixes — blog.laozhang.ai