Femoon's Blog

Claude Code 配置 ccstatusline 状态栏

15分钟阅读

Claude Code 配置 ccstatusline 状态栏

场景：给 Claude Code（以下简称 CC）配一个信息丰富的底部状态栏——一行显示当前目录、模型、上下文用量、git 分支和改动数。用 ccstatusline 这个现成的渲染器即可。三步搞定：全局安装、写一份配置、把 statusLine 接进 settings.json。两套系统这份配置完全一样，区别只在安装方式和路径写法：Windows 的 statusLine 命令实际经 Git bash 执行，路径得用 /c/... 正斜杠写法（反斜杠会被吞）；macOS 用原生路径即可，且推荐用 bun 全局装来绕开 fnm/nvm 的临时路径坑。

ccstatusline 是什么

ccstatusline 是一个专门给 Claude Code 用的状态栏渲染器。CC 每次刷新底部状态栏时，会把当前会话的一段 JSON（模型、工作目录、transcript 路径等）通过 stdin 喂给你在 settings.json 里配的 statusLine.command，命令把它渲染成一行文本打到 stdout。ccstatusline 就是这么一个命令——你用一份声明式配置描述「这行里要放哪些组件、什么颜色、怎么排版」，它负责拼好那行。

它的配置存在 ~/.config/ccstatusline/settings.json（当前 config schema 是 version: 3），既可以手写，也可以跑 ccstatusline 进交互式 TUI 点选生成。本文给一份现成的配置直接用。

省流：一句 prompt 让 CC 自己配好

配置好后的效果：

想看清楚每步在干嘛，继续往下读。

前置

  • 装好 Node.js / npm（确认 node -v、npm -v 有版本号）。两套系统默认都用 npm 装；macOS 上如果你已装了 bun，更推荐用 bun（原因见步骤一）。
  • 知道自己的用户主目录：下文 Windows 统一写 C:\Users\<你>、macOS 写 ~（或 /Users/<你>），实际替换成你的用户名。

步骤一：全局安装 ccstatusline

npm install -g ccstatusline@2.2.19

装完查出全局安装目录（步骤三要用它拼路径）：

npm prefix -g   # 默认 C:\Users\<你>\AppData\Roaming\npm

npm 在这个目录里给 ccstatusline 生成了三个入口：ccstatusline（无扩展名的 sh 脚本）、ccstatusline.cmd、ccstatusline.ps1。步骤三要用的是无扩展名的那个 ccstatusline——因为 statusLine 命令走 bash（下文细说），bash 跑的是 sh 脚本，不是 .cmd。

钉版本 @2.2.19 是为了让配置文件的 schema（version: 3）和程序对得上；想用最新版就去掉 @2.2.19，但配置字段可能要相应调整。

如果你的 node 是 fnm / nvm-windows 管的，npm prefix -g 给出的目录会不一样：fnm 下它往往是 per-session 的临时路径（形如 ...\fnm_multishells\<随机数字>\），会话一换数字就变，绝不能写进配置。改用稳定的版本安装目录，例如 C:\Users\<你>\AppData\Roaming\fnm\node-versions\v<版本>\installation\ccstatusline。代价是路径里带 node 版本号，将来升级/切换 node 版本后要相应更新。

macOS 同样用 npm 全局安装，装完用 which 查出二进制绝对路径（步骤三要用）：

npm install -g ccstatusline@2.2.19
which ccstatusline   # 例如 /opt/homebrew/bin/ccstatusline

和 Windows 一样，如果你的 node 由 fnm / nvm 管，which 给出的可能是含 fnm_multishells 的临时路径，会话一换就失效，别写进配置——这种情况见下面用 bun 固定路径。

装了 bun 的话更推荐用 bun 全局装：bun install -g ccstatusline@2.2.19，二进制固定落在 ~/.bun/bin/ccstatusline。bun 不走 node 那套版本管理，这条路径稳定不变，天然没有 fnm/nvm 临时路径的问题，省去 which 复核这一步。

步骤二：写配置文件

ccstatusline 读 os.homedir()/.config/ccstatusline/settings.json：Windows 上即 C:\Users\<你>\.config\ccstatusline\settings.json，macOS 上即 ~/.config/ccstatusline/settings.json。两套系统这份 JSON 完全一样。 新建这个目录，写入：

{
  "version": 3,
  "lines": [
    [
      {
        "id": "8b9f66f2-2716-4d73-afe6-a44f5572aa8b",
        "type": "current-working-dir",
        "rawValue": true,
        "metadata": { "fishStyle": "true" }
      },
      { "id": "2", "type": "separator" },
      { "id": "1", "type": "model", "color": "cyan", "rawValue": true },
      { "id": "93879268-0b50-4717-9fff-60fedaffb2e6", "type": "separator" },
      {
        "id": "3",
        "type": "context-length",
        "color": "brightBlack",
        "rawValue": true,
        "merge": true
      },
      { "id": "ctx-gap", "type": "custom-text", "customText": " ", "merge": true },
      {
        "id": "76157311-b9df-422b-96a3-0f05a35ad28e",
        "type": "context-percentage-usable",
        "rawValue": true
      },
      { "id": "4", "type": "separator" },
      { "id": "5", "type": "git-branch", "color": "magenta" },
      { "id": "6", "type": "separator" },
      { "id": "7", "type": "git-changes", "color": "yellow" }
    ],
    [],
    []
  ],
  "flexMode": "full-until-compact",
  "compactThreshold": 60,
  "colorLevel": 2,
  "inheritSeparatorColors": false,
  "globalBold": false,
  "gitCacheTtlSeconds": 5,
  "minimalistMode": false,
  "powerline": {
    "enabled": false,
    "separators": [""],
    "separatorInvertBackground": [false],
    "startCaps": [],
    "endCaps": [],
    "autoAlign": false,
    "continueThemeAcrossLines": false
  },
  "installation": { "method": "pinned", "installedVersion": "2.2.19" }
}

这份配置的状态栏从左到右是：

组件说明颜色
current-working-dir（fishStyle）当前目录，fish 风格缩写中间层（D:\P\work）默认
model当前模型名cyan
context-length + context-percentage-usable上下文已用 token 数 + 可用百分比brightBlack
git-branch当前分支（⎇ main）magenta
git-changes工作区改动 (+增, -删)yellow

各组件之间用 separator 隔开。flexMode: full-until-compact 是终端窄到一定程度（compactThreshold）才折叠成精简版。不想手写就跑 ccstatusline 进 TUI 点选，效果一样。

步骤三：把 statusLine 接进 settings.json

编辑 CC 的 settings.json（Windows：C:\Users\<你>\.claude\settings.json；macOS：~/.claude/settings.json），加上（或替换原有的）statusLine 字段。

Windows——command 指向步骤一里 npm prefix -g 目录下那个无扩展名的 ccstatusline，并且写成 /c/Users/... 正斜杠路径，不是 C:\Users\...（原因下一节说）：

"statusLine": {
  "type": "command",
  "command": "/c/Users/<你>/AppData/Roaming/npm/ccstatusline",
  "padding": 0,
  "refreshInterval": 10
}

macOS——直接写 which ccstatusline 查到的原生绝对路径，没有任何转义讲究（npm 装的常见于 /opt/homebrew/bin/ccstatusline 或 /usr/local/bin/ccstatusline，bun 装的是 /Users/<你>/.bun/bin/ccstatusline）：

"statusLine": {
  "type": "command",
  "command": "/opt/homebrew/bin/ccstatusline",
  "padding": 0,
  "refreshInterval": 10
}

refreshInterval: 10 是状态栏刷新间隔（秒），padding: 0 去掉左右额外空格。下一节解释 Windows 为什么必须正斜杠、为什么指无扩展名那个——这一节是 Windows 专属，macOS 可直接跳到「验证」。

一个 Windows 专属的点：statusLine 命令走的是 bash，不是 PowerShell

直觉上你会把命令写成 Windows 原生路径：

"command": "C:\\Users\\<你>\\AppData\\Roaming\\npm\\ccstatusline"

结果是——状态栏空白，什么都不显示。

原因：CC 的 statusLine.command（以及 hook 命令）在本机是交给 Git bash 执行的，不是 PowerShell。bash 把反斜杠当转义符，C:\Users\... 里的 \U、\A、\R 等全被吃掉，路径塌成一坨：

# 反斜杠路径 → 找不到命令
$ C:\Users\Yang\AppData\Roaming\npm\ccstatusline
/usr/bin/bash: line 1: C:UsersYangAppDataRoamingnpmccstatusline: command not found
 
# MSYS 正斜杠路径 → 正常渲染
$ /c/Users/Yang/AppData/Roaming/npm/ccstatusline
D:\P\hapi | Opus |  ⎇ main | (+1675,-1673)

所以 Windows 下 statusLine.command 的路径必须 MSYS 正斜杠化：盘符 C:\ 写成 /c/，其余 \ 换 /。这也是为什么步骤一要用无扩展名的 ccstatusline（sh 脚本）而不是 .cmd——bash 跑的是前者。

顺带一提：settings.json 里的 defaultShell: "powershell" 管的是 CC 输入框里 !<命令> 用哪个 shell，不影响 statusLine 和 hook 命令的执行 shell——后者照样走 bash。这点和 Claude Code 在 Windows 下强制走 PowerShell 的配置教程 里关于 hook 命令的结论是一致的。

验证

1. 命令本身能渲染——用一段模拟的会话 JSON 喂给它。

Windows（经 bash 执行，复刻真实路径）：

'{"workspace":{"current_dir":"D:\\Project\\hapi"},"model":{"display_name":"Opus"},"cwd":"D:\\Project\\hapi"}' | & "C:\Program Files\Git\bin\bash.exe" -c '/c/Users/<你>/AppData/Roaming/npm/ccstatusline'

macOS（原生管道直接喂，$(which ccstatusline) 自动用上你装好的那个）：

echo '{"workspace":{"current_dir":"/Users/<你>/Project/demo"},"model":{"display_name":"Opus"},"cwd":"/Users/<你>/Project/demo"}' | $(which ccstatusline)

预期输出一行彩色状态栏，类似：

~/P/demo | Opus | ⎇ main | (+4,-0)

2. settings.json 仍是合法 JSON：

# Windows
Get-Content "C:\Users\<你>\.claude\settings.json" -Raw | ConvertFrom-Json | Out-Null
# macOS
python3 -m json.tool ~/.claude/settings.json > /dev/null && echo OK

不报错即可。

3. 实际生效：配置变更需要新会话加载，重开一个 CC 会话，底部就能看到状态栏。切到一个有 git 改动的目录，确认分支名和 (+N,-N) 改动数正常跳动。

常见问题

Q: statusLine 到底走哪个 shell？为什么不是 PowerShell？

A: 本机是 Git bash。CC 的 statusLine / hook 命令默认交给 bash 执行，跟 defaultShell 设成什么无关（defaultShell 只管输入框的 !cmd）。所以命令里的 Windows 路径要写成 /c/... 正斜杠形式，反斜杠会被 bash 吞掉。

Q: command 为什么指向无扩展名的 ccstatusline，不是 ccstatusline.cmd？

A: npm 全局安装会同时生成 ccstatusline（sh 脚本）、ccstatusline.cmd、ccstatusline.ps1 三个入口。statusLine 走 bash，bash 执行的是 sh 脚本那个，所以指向无扩展名的 ccstatusline。.cmd 是给 cmd.exe 用的，bash 直接跑会出错。

Q: 配置文件到底放哪？~/.config 在 Windows 解析到哪？

A: ccstatusline 用 os.homedir()/.config/ccstatusline/settings.json，Windows 下 os.homedir() 就是 C:\Users\<你>，所以路径是 C:\Users\<你>\.config\ccstatusline\settings.json。和有没有别的 XDG 设置无关。

Q: 状态栏里 context 百分比，为什么我用模拟 JSON 测试时不显示？

A: context 长度/百分比依赖真实的 transcript 文件。模拟 JSON 里没有 transcript_path（或指向空），自然算不出 token 数。在真实会话里会正常显示，不用担心。

Q: 改完不显示，怎么排查？

A: 按这个顺序：①先用上面「验证」里的 bash 管道手测命令路径能不能跑出东西——多半是路径反斜杠没改成 /c/...，或指向了 .cmd 而不是无扩展名的 ccstatusline；②npm prefix -g 复核全局目录和你写进 command 的是否一致；③完全退出 CC 再重开（不是刷新，是重启进程）让 settings.json 重新加载。

Q: macOS 上和 Windows 有什么不同？

A: 配置 JSON 完全一样，区别在安装与路径：① 安装默认也用 npm（npm install -g ccstatusline@2.2.19，装完 which ccstatusline 查绝对路径）；若装了 bun 更推荐 bun install -g——bun 不走 node 那套版本管理，二进制固定在 ~/.bun/bin/ccstatusline，不会出现 fnm/nvm 那种临时路径问题；② statusLine.command 直接写 which 查到的原生绝对路径，没有 Windows 那套 /c/... 正斜杠和无扩展名 shim 的讲究——因为 macOS 不存在路径被 bash 吞的问题。配置文件同样在 ~/.config/ccstatusline/settings.json。

Q: 想换显示内容或配色怎么办？

A: 直接跑 ccstatusline 进交互式 TUI，增删组件、调颜色、调 flexMode，存盘即写回 ~/.config/ccstatusline/settings.json；或者手改那份 JSON 也行。

配置清单

  • 全局安装：Windows npm install -g ccstatusline@2.2.19 + npm prefix -g 查目录（默认 C:\Users\<你>\AppData\Roaming\npm）；macOS npm install -g ccstatusline@2.2.19 + which ccstatusline 查绝对路径（装了 bun 更推荐 bun install -g，二进制固定在 ~/.bun/bin/ccstatusline，无 fnm/nvm 临时路径问题）
  • 写配置到 ~/.config/ccstatusline/settings.json（Windows 即 C:\Users\<你>\.config\...，上文 JSON，两系统一致）
  • CC 的 settings.json 加 statusLine：Windows 用 /c/Users/<你>/AppData/Roaming/npm/ccstatusline 正斜杠路径、无扩展名；macOS 用 which 查到的原生绝对路径（如 /opt/homebrew/bin/ccstatusline 或 ~/.bun/bin/ccstatusline）
  • 模拟 JSON 管道验证渲染 + 验证 settings.json 合法（Win ConvertFrom-Json／mac python3 -m json.tool）+ 重开会话看效果

参考

官方/社区

本 vault 相关笔记