# Claude Code 状态栏

> Claude Code status line 的 /statusline 配置、JSON 输入字段、成本和上下文显示、刷新机制、Windows 兼容与缓存影响。

URL: https://docs.passion8.cc/docs/claude-code/statusline
Language: zh-CN
Publisher: Passion8

Status line 是 Claude Code 底部的一行自定义状态栏。它运行你配置的本地命令,把当前会话 JSON 通过 stdin 传进去,然后把命令 stdout 显示在终端底部。




状态栏脚本本地执行,不会消耗模型 token。它适合显示上下文占用、模型、会话成本、Git 分支、PR 状态、rate limit 和当前 output style。




## 快速配置

最简单的方式是让 Claude Code 生成:

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

手动配置则在 `settings.json` 写 `statusLine`:

```json title="~/.claude/settings.json"
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 2
  }
}
```

也可以直接写 inline command:

```json title="~/.claude/settings.json"
{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}
```

## 一个可用脚本

```bash title="~/.claude/statusline.sh"
#!/bin/bash
input=$(cat)

model=$(echo "$input" | jq -r '.model.display_name // .model.id // "model"')
dir=$(echo "$input" | jq -r '.workspace.current_dir // .cwd')
pct=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
branch=$(git -C "$dir" branch --show-current 2>/dev/null || true)

printf "[%s] %s" "$model" "${dir##*/}"
[ -n "$branch" ] && printf " · %s" "$branch"
printf " · %s%% context · $%s\n" "$pct" "$cost"
```

启用:

```bash
chmod +x ~/.claude/statusline.sh
```

## 刷新机制

| 触发 | 行为 |
| --- | --- |
| assistant 新回复后 | 重新运行脚本 |
| `/compact` 完成后 | 更新上下文和成本字段 |
| 权限模式变化 | 更新权限相关展示 |
| Vim mode 切换 | 更新 `vim.mode` |
| `refreshInterval` | 额外按秒定时刷新 |

更新有约 300ms debounce。新更新到来时,还没结束的脚本会被取消。脚本输出可以多行,也可以包含 ANSI 颜色和终端支持的 OSC 8 链接。




状态栏脚本不要太慢。它在本机频繁运行,脚本里做网络请求、跑重命令或扫描大仓库,会让 Claude Code TUI 变卡。




## 常用字段

| 字段 | 用途 |
| --- | --- |
| `model.id`、`model.display_name` | 当前模型 |
| `workspace.current_dir`、`cwd` | 当前目录 |
| `workspace.project_dir` | 启动目录 |
| `workspace.added_dirs` | `/add-dir` 和 `--add-dir` 增加的目录 |
| `cost.total_cost_usd` | Claude Code 客户端估算成本 |
| `context_window.used_percentage` | 当前上下文占用比例 |
| `context_window.current_usage.cache_read_input_tokens` | 最近一次请求读缓存 token |
| `context_window.current_usage.cache_creation_input_tokens` | 最近一次请求写缓存 token |
| `rate_limits.five_hour.used_percentage` | 5 小时窗口用量比例 |
| `session_id`、`session_name` | 会话标识和名称 |
| `prompt_id` | 当前 prompt UUID,可和 OTel 事件关联 |
| `output_style.name` | 当前 output style |
| `agent.name` | `--agent` 或 settings 指定的主 agent |
| `pr.number`、`pr.review_state` | 当前分支 PR 信息 |
| `worktree.name`、`worktree.branch` | `--worktree` 会话信息 |

## 和 Passion8 的关系

状态栏读的是 Claude Code 本地会话数据。接入 Passion8 后,你最应该展示:

| 目标 | 字段 |
| --- | --- |
| 看缓存是否命中 | `cache_read_input_tokens` 和 `cache_creation_input_tokens` |
| 看上下文是否该整理 | `context_window.used_percentage` |
| 看会话成本趋势 | `cost.total_cost_usd` |
| 区分多个任务 | `session_name`、`workspace.current_dir`、`worktree.name` |

`cost.total_cost_usd` 是客户端估算,不一定等于 Passion8 最终账单。实际余额和扣费仍以 Passion8 控制台为准。

## Windows 配置

PowerShell 也能做状态栏:

```powershell title="$HOME\\.claude\\statusline.ps1"
$inputJson = [Console]::In.ReadToEnd() | ConvertFrom-Json
$model = $inputJson.model.display_name
$pct = $inputJson.context_window.used_percentage
Write-Output "[$model] $pct% context"
```

settings:

```json title="~/.claude/settings.json"
{
  "statusLine": {
    "type": "command",
    "command": "powershell -ExecutionPolicy Bypass -File \"$HOME\\.claude\\statusline.ps1\""
  }
}
```

## 缓存影响

| 动作 | 对 5m / 1h 缓存的影响 |
| --- | --- |
| 新增或修改 `statusLine` | 不改变当前 system prompt,通常不导致模型缓存失效 |
| `/statusline` 生成脚本 | 生成过程本身是普通对话,按普通追问命中缓存 |
| 状态栏脚本刷新 | 本地执行,不调用模型,不消耗 token |
| 脚本运行 Git 或 shell 命令 | 只影响本机性能,不会进入模型上下文 |

## 官方参考

- [Customize your status line](https://code.claude.com/docs/en/statusline.md)
- [Settings](https://code.claude.com/docs/en/settings.md)
- [Prompt caching](https://code.claude.com/docs/en/prompt-caching.md)