Claude Code 深度学习手册

主题

Status Line（状态栏） ​

Claude Code 底部一条可定制的状态栏，运行你配置的 shell 脚本（脚本从 stdin 读 JSON 会话数据、打印文本到 stdout），用来持续展示上下文用量、成本、git 状态等信息。

你的真实情况 ​

你有内置的 statusline-setup agent 可用（专门帮你配状态栏）。状态栏 = 终端底部那行自定义信息（模型、目录、git 分支、token 占用等），由一个脚本动态生成。

去真实体验 ​

想验证什么这样做
一键配置状态栏/statusline（会调 statusline-setup agent）
手动配settings.json 加 "statusLine": { "type": "command", "command": "~/.claude/statusline.sh" }

对你的实际意义 ​

你同时在跑多个项目（前端/SpringBlade/docs）+ 用 worktree + ralph-loop，状态栏放上 git 分支 + 当前目录 + 上下文占用 很实用——一眼知道自己在哪个 worktree、上下文快满没。脚本从 stdin 收 JSON（含 model、cwd、git 等），输出一行即可。

官方文档要点 ​

以下为按官方文档整理的系统性参考。

是什么 ​

Status line 是 Claude Code 界面底部的可定制状态条，会运行你在设置里配置的任意 shell 脚本。它通过 stdin 收到 JSON 会话数据，显示脚本打印的任何内容，给你一个持续、一目了然的视图（上下文用量、成本、git 状态等）。它本地运行、不消耗 API token；在自动补全建议、帮助菜单、权限提示等 UI 交互期间会临时隐藏。

怎么工作 ​

  • 数据流：Claude Code 运行你配置的脚本，把 JSON 会话数据通过 stdin 管道传给脚本；脚本读 JSON、提取字段、把文本打印到 stdout；Claude Code 原样显示。状态栏本地运行，不消耗 API token。
  • 触发时机：脚本在这些事件后运行——每条新 assistant 消息后、/compact 完成后、权限模式变化时、vim 模式切换时。更新有 300ms 防抖，快速变化批量合并后只跑一次。
  • 并发取消：脚本还在跑时又来新更新，正在执行的那次被取消。编辑脚本后改动要等下次交互触发更新才生效。
  • 空闲补更新：主会话空闲（如协调者等后台 subagent）时触发会变安静；要让时间相关或外部数据的段保持新鲜，设 refreshInterval 用固定计时器额外重跑。
  • 输出能力：每个 echo/print 单独成一行；支持 ANSI 色码如 \033[32m；支持 OSC 8 转义做可点击链接（macOS Cmd+click / Win&Linux Ctrl+click）。
  • 终端尺寸：Claude Code 捕获脚本输出而非直连终端，tput cols 读不到尺寸；改读环境变量 COLUMNS 和 LINES，需 v2.1.153+。
  • 上下文百分比：used_percentage 只按输入算（input_tokens + cache_creation_input_tokens + cache_read_input_tokens），不含 output_tokens；v2.1.132 起 total_input/output_tokens 反映当前上下文占用而非会话累计。
  • subagentStatusLine：每刷新 tick 跑一次，所有可见 subagent 行作为单个 JSON 传到 stdin；脚本对每行输出一行 JSON {"id":"<task id>","content":"..."}，省略 id 保留默认，content 空串则隐藏。

怎么配置 / 用法 ​

配置位置：用户设置 ~/.claude/settings.json，或项目设置（见 /en/settings）。最小配置：

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

type 必须为 "command"；command 指向脚本路径或内联 shell 命令。内联例（用 jq 读 stdin）：

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

可选字段：padding（额外横向间距字符数，默认 0）、refreshInterval（每 N 秒重跑，最小值 1）、hideVimModeIndicator（true 时隐藏内置 -- INSERT --）。 两种创建方式：(1) 斜杠命令 /statusline 自然语言描述，Claude 自动在 ~/.claude/ 生成脚本并改设置，例如 /statusline show model name and context percentage with a progress bar；(2) 手写脚本 + 改 settings.json。 脚本三步：写脚本读 stdin → chmod +x ~/.claude/statusline.sh → 加进 settings.json。 删除：运行 /statusline delete（或 clear/remove），或手动删 statusLine 字段。 子 agent 行用 subagentStatusLine 字段（同结构 type/command）。 测试：echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ./statusline.sh

什么时候用 ​

  • 想随时监控上下文窗口用量（context window usage）时用
  • 需要跟踪会话成本（session cost）时用
  • 跨多个会话工作、需要区分不同会话时用
  • 想让 git 分支和状态始终可见时用
  • 想给后台 subagent 行自定义渲染时用 subagentStatusLine
  • 别用于需要消耗 API/联网的重操作——脚本运行频繁，慢脚本会拖慢界面（应缓存 git status 等慢命令）
  • 脚本输出别太长——状态栏宽度有限，过长会被截断或换行错乱

限制 / 坑 ​

  • 脚本若以非零退出码退出或无任何输出，状态栏会变空白。
  • 慢脚本会阻塞状态栏更新直到完成，导致显示陈旧；脚本仍在跑时来新更新会被取消。
  • 必须接受 workspace 信任对话框才会运行（因为 statusLine 执行 shell 命令，和 hooks 同样需要信任）；未信任时显示 statusline skipped · restart to fix，需重启并接受信任提示。
  • 若 settings 里 disableAllHooks 设为 true，状态栏也会被一并禁用。
  • Claude Code 捕获输出，脚本内 tput cols、语言级宽度检测无效，必须读 COLUMNS/LINES 环境变量（需 v2.1.153+）。
  • 编辑脚本后改动不会立即出现，要等下一次与 Claude Code 交互触发更新。
  • OSC 8 链接：Terminal.app 不支持；Windows Terminal 等可能未被自动检测，需设 FORCE_HYPERLINK=1；SSH/tmux 可能按配置剥离 OSC 序列。
  • 转义序列若与其他 UI 更新重叠可能产生乱码；多行+转义码比单行纯文本更易出渲染问题。
  • 成本字段 cost.total_cost_usd 是客户端估算，可能与实际账单不同。
  • exceeds_200k_tokens 是固定 200k 阈值，与实际上下文窗口大小无关。
  • 系统通知（MCP 错误、自动更新、context-low 警告）与状态栏共用同一行右侧，窄终端下可能截断你的输出；verbose 模式会在该区加 token 计数。
  • 许多字段可能缺失或为 null（见 keyFacts），脚本必须做条件访问和 fallback 默认值处理。

硬事实速查（28 条） ​

  • 配置文件：~/.claude/settings.json（用户级）或项目设置；字段为 statusLine，需 type: "command" 和 command（脚本路径或内联命令）。
  • 斜杠命令：/statusline <自然语言描述> 自动生成脚本到 ~/.claude/ 并改设置；删除用 /statusline delete / clear / remove。
  • 可选字段 padding：额外横向间距（字符数），默认 0，是相对缩进而非到终端边的绝对距离。
  • 可选字段 refreshInterval：每 N 秒额外重跑命令，最小值 1；不设则只在事件时跑。
  • 可选字段 hideVimModeIndicator：设 true 时隐藏内置 -- INSERT --（当脚本自己渲染 vim.mode 时用）。
  • 更新触发：新 assistant 消息后 / /compact 完成后 / 权限模式变化 / vim 模式切换；防抖 300ms；脚本运行中来新更新则取消在飞执行。
  • 终端尺寸环境变量：COLUMNS 和 LINES，由 Claude Code 运行脚本前设置，需 Claude Code v2.1.153 或更高。
  • JSON 字段 model：model.id、model.display_name。
  • JSON 字段目录：cwd 与 workspace.current_dir 同值（推荐后者）、workspace.project_dir（启动目录）、workspace.added_dirs（/add-dir 或 --add-dir 加的，默认空数组）、workspace.git_worktree。
  • JSON 字段仓库：workspace.repo.host、workspace.repo.owner、workspace.repo.name（从 origin remote 解析，如 github.com/anthropics/claude-code），无仓库或无 origin 时缺失。
  • JSON 字段成本：cost.total_cost_usd（客户端估算 USD）、cost.total_duration_ms（会话墙钟时间 ms）、cost.total_api_duration_ms（等 API 响应时间 ms）、cost.total_lines_added、cost.total_lines_removed。
  • JSON 字段上下文：context_window.total_input_tokens、context_window.total_output_tokens（v2.1.132 前为会话累计，之后为当前上下文）、context_window.context_window_size（默认 200000，扩展上下文模型为 1000000）、context_window.used_percentage、context_window.remaining_percentage、context_window.current_usage。
  • context_window.current_usage 含 input_tokens、output_tokens、cache_creation_input_tokens、cache_read_input_tokens；首次 API 调用前为 null，/compact 后到下次 API 调用前再次为 null。
  • used_percentage 只按输入算：input_tokens + cache_creation_input_tokens + cache_read_input_tokens，不含 output_tokens。
  • exceeds_200k_tokens：最近一次 API 响应总 token（输入+缓存+输出）是否超 200k，固定阈值。
  • effort.level：取值 low/medium/high/xhigh/max；ultracode 不是独立等级、上报为 xhigh；模型不支持 effort 参数时缺失。
  • thinking.enabled：是否启用扩展思考。
  • 速率限制：rate_limits.five_hour.used_percentage、rate_limits.seven_day.used_percentage（0-100）、rate_limits.five_hour.resets_at、rate_limits.seven_day.resets_at（Unix epoch 秒）；仅 Claude.ai 订阅者（Pro/Max）首次 API 响应后出现，两窗口可独立缺失，用 // empty 处理。
  • 其他 JSON 字段：session_id、session_name（--name 或 /rename 设置，否则缺失）、transcript_path、version、output_style.name、vim.mode（NORMAL/INSERT/VISUAL/VISUAL LINE，仅 vim 模式开启时）、agent.name（--agent 或 agent 设置时）。
  • PR 字段：pr.number、pr.url、pr.review_state（approved/pending/changes_requested/draft）；无 PR/非仓库/PR 合并或关闭后缺失，review_state 可独立缺失。
  • worktree 字段：worktree.name、worktree.path、worktree.branch（如 worktree-my-feature）、worktree.original_cwd、worktree.original_branch；仅 --worktree 会话存在，hook-based worktree 下 branch/original_branch 可能缺失。
  • 颜色码示例：\033[32m 绿、\033[33m 黄、\033[31m 红、\033[36m 青、\033[0m 重置；多行=每个 echo/print 一行。
  • OSC 8 链接格式：\e]8;;URL\a + TEXT + \e]8;;\a；Bash 用 printf '%b' 比 echo -e 更可靠跨 shell。
  • 缓存慢操作：用 JSON 的 session_id 做缓存文件名（会话内稳定、跨会话唯一），别用 $$/os.getpid()/process.pid（每次调用都变会失效）；示例缓存 5 秒。
  • Windows：装了 Git Bash 走 Git Bash，否则走 PowerShell；command 路径必须用正斜杠（反斜杠会被当转义吃掉导致静默失败），~ 可用；PowerShell 脚本用 powershell -NoProfile -File C:/.../statusline.ps1 调用。
  • subagentStatusLine：单独设置字段（type/command），输入含 base hook 公共字段 + columns（可用行宽）+ tasks 数组，每个 task 有 id/name/type/status/description/label/startTime/tokenCount/tokenSamples/cwd；输出每行 {"id":...,"content":...}；受同样的 trust 与 disableAllHooks 门控；插件可在其 settings.json 内置默认。
  • 调试：claude --debug 记录会话首次 statusline 调用的退出码和 stderr；FORCE_HYPERLINK 设法：FORCE_HYPERLINK=1 claude，PowerShell 用 $env:FORCE_HYPERLINK = "1"; claude。
  • 社区项目：ccstatusline（github.com/sirmalloc/ccstatusline）、starship-claude（github.com/martinemde/starship-claude）。

官方出处：https://code.claude.com/docs/en/statusline