ccstatusline零基础教程

一份面向 Claude Code 用户的渐进式教程。前半部分零基础友好，每一步都讲清楚"按什么、看到什么"；后半部分给中级用户准备了技术原理、hook 协议、payload schema、缓存机制、Custom Command、Powerline 与故障排查。读完你就能从"会用"升级到"会改、会调、会接外部数据"。

目录

• 一、什么是 ccstatusline
• 二、技术原理：Claude Code 的 statusLine hook
• 三、安装
• 四、TUI 操作速查
• 五、零基础 12 步教程
• 六、所有可用组件一览
• 七、settings.json 完整字段解析
• 八、进阶玩法
• 九、Custom Command：接入外部脚本
• 十、Powerline 美化
• 十一、性能与缓存机制
• 十二、调试与排障
• 十三、Q&A 速查
• 十四、备份与多机同步

一、什么是 ccstatusline

ccstatusline 是 Matthew Breedlove（@sirmalloc）开源的状态栏格式化器，专门给 Claude Code CLI 使用。它的核心思路是：

• Claude Code 在 settings.json 里支持一个 statusLine 命令钩子（hook），会把当前会话的 JSON 信息通过 stdin 送给你的命令；
• ccstatusline 接收这份 JSON，按你预设的"组件 (widget)"渲染出一行或多行状态文本，再通过 stdout 返回给 Claude Code 显示在底部状态栏。

它的卖点：

• 40+ 内建组件：模型名、Token 总量、Git 分支/改动、会话耗时、会话花费、5 小时块计时、每周用量、内存占用、自定义文本…
• 多行布局：早期上限 3 行，v2.0.11 之后已无行数限制；
• Powerline 风格：箭头分隔符、起止 cap、自动对齐；
• TUI 配置界面：基于 React/Ink 的交互式终端 UI，配置好直接预览；
• 零配置可用：npx ccstatusline 直接跑，所有变更通过 TUI 完成，无需手写 JSON；
• 跨平台：macOS / Linux / Windows / WSL；同时兼容 Node 与 Bun。

二、技术原理：Claude Code 的 statusLine hook

理解 ccstatusline 之前，先理解它是怎么"被调用"的。这一节是中级用户必看，新手可以先跳过、用一阵再回头看。

2.1 hook 注册：Claude Code 端

Claude Code 读取 ~/.claude/settings.json，识别 statusLine 字段：

{
  "statusLine": {
    "type": "command",
    "command": "ccstatusline",
    "padding": 0,
    "refreshInterval": 10
  }
}

字段含义：

2.2 调用生命周期

每次 Claude Code 需要刷新状态栏时（事件触发或定时器到点），它会：

1. 启动一个子进程执行你的 command；
2. 通过 stdin 把当前会话的 JSON 数据 pipe 进去；
3. 等子进程 stdout 输出文本，作为状态栏内容显示；
4. 子进程退出。

ccstatusline 的入口 main() 函数会检测 process.stdin.isTTY：

• 非 TTY（有 pipe 进来的数据）→ 解析 JSON，渲染状态栏；
• 是 TTY（你在终端里直接跑 ccstatusline）→ 启动 TUI 配置界面。

这就是为什么同一个二进制既能当 hook 用又能当配置工具用。

2.3 Payload Schema：Claude Code 传了什么

来自 ccstatusline 源码里的 StatusJSONSchema，这是 Claude Code 通过 stdin 传给状态栏程序的完整 JSON 结构：

{
  hook_event_name?: string;          // 触发事件名（如 "UserPromptSubmit"）
  session_id?: string;               // 会话 ID
  transcript_path?: string;          // 会话 JSONL 转录文件路径
  cwd?: string;                      // 当前工作目录
  version?: string;                  // Claude Code 版本

  model?: string | {                 // 模型信息
    id?: string;
    display_name?: string;
  };

  workspace?: {
    current_dir?: string;
    project_dir?: string;
  };

  output_style?: { name?: string };  // 输出风格名（如 "concise"）
  effort?: { level?: string };       // 思考强度（low/medium/high/xhigh）
  vim?:    { mode?: string };        // Vim 模式（normal/insert 等）

  cost?: {                           // 会话花费
    total_cost_usd?: number;
    total_duration_ms?: number;
    total_api_duration_ms?: number;
    total_lines_added?: number;
    total_lines_removed?: number;
  };

  context_window?: {                 // 上下文窗口
    context_window_size?: number;
    total_input_tokens?: number;
    total_output_tokens?: number;
    current_usage?: number | {
      input_tokens?: number;
      output_tokens?: number;
      cache_creation_input_tokens?: number;
      cache_read_input_tokens?: number;
    };
    used_percentage?: number;
    remaining_percentage?: number;
  };

  worktree?: {                       // Git worktree 信息
    name?: string;
    path?: string;
    branch?: string;
    original_cwd?: string;
    original_branch?: string;
  };

  rate_limits?: {                    // 限速桶
    five_hour?:        { used_percentage?: number; resets_at?: number };
    seven_day?:        { used_percentage?: number; resets_at?: number };
    seven_day_sonnet?: { used_percentage?: number; resets_at?: number };
    seven_day_opus?:   { used_percentage?: number; resets_at?: number };
  };
}

💡 这是 looseObject，意味着 Claude Code 可能传更多字段，ccstatusline 不会因此报错。

2.4 额外信息从哪来

ccstatusline 显示的有些信息并不在上面这份 payload 里。它会主动去这些地方拿：

2.5 渲染流程

进入 renderMultipleLines(data) 后大致是这样：

1. 加载 ~/.config/ccstatusline/settings.json；
2. 异步并行收集 token metrics、speed metrics、session duration（如果配置里启用了相关 widget）；
3. 遍历 lines，对每行依次渲染 widget：
   • 每个 widget 实例从 payload + 外部数据源拿值；
   • 应用颜色、padding、是否 raw、是否粗体；
   • 拼接分隔符；
4. 处理 flex separator（撑开占满终端宽度）；
5. 应用 Powerline 装饰（如果开启）；
6. 输出到 stdout。

整个过程通常在几十毫秒到几百毫秒内完成。Git 缓存（5 秒 TTL）与 Block Timer 缓存（按 5 小时块失效）是性能关键。

三、安装

3.1 前置要求

• Node.js ≥ 14
• 已安装并登录 Claude Code CLI
• （可选）支持 Powerline 字体的终端（iTerm2、Windows Terminal、Alacritty 等）

3.2 三种安装方式

ccstatusline 不强制全局安装。它本身就是一个可以 npx/bunx 直接拉起的小工具：

方式 A：临时运行（最快上手）

# 用 npm
npx -y ccstatusline@latest

# 或用 bun（更快）
bunx -y ccstatusline@latest

执行后直接进入 TUI 配置界面。

方式 B：固定版本全局安装（推荐长期使用）

进入 TUI 后选择 Pinned global install。它会：

1. 把当前 ccstatusline 版本通过 npm/bun 全局安装到本机；
2. 在 Claude Code 的 settings.json 里写入 "command": "ccstatusline"（不再带 @latest）。

这样 Claude Code 永远使用你确认过的那个版本。之后再次想打开配置界面，直接执行：

ccstatusline

方式 C：自动跟随最新版

TUI 安装时可以选择把命令写成 npx -y ccstatusline@latest。每次 Claude Code 触发状态栏渲染时都会跑一次 npx 解析（有冷启动延迟，但永远是最新版）。

3.3 升级与卸载

• 升级 Pinned 版本：在 TUI 里 Uninstall，重新进 TUI 选 Pinned global install 即可；本地 settings.json 不会被卸载流程清除。
• 完全移除：TUI 里 Uninstall + npm uninstall -g ccstatusline。

四、TUI 操作速查

进入 ccstatusline 后是一个键盘驱动的菜单：

进入某行后：

• a：add widget（带搜索/模糊匹配/initialism 匹配的组件选择器，v2.2.8 起）
• k：clone（克隆当前组件，Powerline 模式下会给新色）
• 方向键：移动光标；移动模式下重排
• w：进入 widget editor（每个组件独立的细项）
• u：在「已用 / 剩余」之间切换（用于 Context %、Session Usage 等百分比组件）
• h：隐藏（如 Git 组件在非仓库下不显示 "no git"）
• d：删除当前 widget
• q / Esc：退出 / 返回

通用：菜单/列表导航支持首尾环绕（v2.2.10+）。

五、零基础 12 步教程

第 0 步：确认前置条件

在终端：

claude --version    # 能看到 Claude Code 版本号
node -v             # ≥ v14（建议 v18+）

第 1 步：第一次启动

npx -y ccstatusline@latest

回车，等几秒钟下载，然后进入 TUI 主菜单。

第 2 步：先看默认状态栏长啥样

进入 Lines 菜单，下方有 Preview 区实时渲染。第一次进来通常有几个默认组件（如 Model、Git Branch）。

底部小字提示当前可用快捷键，记住要随时低头看它。

第 3 步：装到 Claude Code

1. Esc 回主菜单 → 移到 Install → Enter；
2. 选 Pinned global install（推荐）；
3. 看到 ✅ 后按 q 退出；
4. 验证：

cat ~/.claude/settings.json | grep -A 3 statusLine

应能看到：

"statusLine": {
  "type": "command",
  "command": "ccstatusline"
}

5. 重启 Claude Code，状态栏出现。🎉

第 4 步：理解 widget

状态栏 = 一堆 widget 拼出来的。典型 widget：

第 5 步：加一个组件

回 TUI（ccstatusline）→ Lines → Line 1：

1. 按 a（add）；
2. 输 cost，过滤出 Session Cost；
3. Enter 选中，Preview 立即出现 Cost: $0.00；
4. 想加分隔符：再按 a → 搜 separator → 选中。

不喜欢位置？停在该 widget 上按 m 进入移动模式，方向键挪动，Enter 确认。

第 6 步：上色

光标停在 Model → 按 w 进 widget editor → 找 Color → Enter 选 cyan。预览立刻变青色。

颜色三档：

• 基础 16 色（cyan / yellow / magenta）—— 兼容性最好，新手选这档
• 256 色（数字 0–255）—— 大多数终端都支持
• truecolor（#a1b2c3）—— 现代终端，色彩最丰富

只用基础色就不用动 colorLevel 设置。

第 7 步：加第二行

Esc 回 Lines → 按 a 加新行 → 进 Line 2 → 加 widget。

新手两行模板：

Line 1：Model | Ctx | Git Branch | Git Changes
Line 2：Session Cost | Session Clock | Block Timer

第 8 步：值得加的"惊喜"组件

第 9 步：自定义文本

a → 搜 custom → 选 Custom Text → w 编辑 → 输入文字（支持中文/emoji）→ Ctrl+S 保存。

第 10 步：自适应宽度（先了解，后调）

• Flex Separator：在两个 widget 间塞一个 flex 分隔符，自动撑开剩余空间；
• Compact Threshold（默认 60）：终端宽度小于此值时，支持紧凑显示的 widget 自动变短。

新手保持默认即可。

第 11 步：测试并理解保存

ccstatusline 自动保存。每改一处 ~/.config/ccstatusline/settings.json 就更新一次。

测试方式：

1. q 退出 TUI；
2. 关闭再打开 Claude Code（或触发一次状态栏刷新）；
3. 看底部是否变成你刚配的样子。

刷新慢？主菜单 → Refresh Interval → 设 5 秒（需 Claude Code ≥ 2.1.97）。

第 12 步：备份

# 配置文件位置
~/.config/ccstatusline/settings.json

放进 dotfiles 或网盘，新机器拷回去再跑一次 TUI 的 Install 就能恢复。

六、所有可用组件一览

按类别罗列（v2.2.19）：

6.1 会话与模型

• model — 模型显示名（自动去掉 (1M context) 后缀）
• model-display — 同上别名
• session-id — 会话 ID
• session-name — /rename 设置的会话名
• session-clock — 会话已运行时长
• session-cost — 会话累计花费（USD）
• session-usage — 本会话 5 小时块用量百分比（含短条模式）
• claude-account-email — 从 ~/.claude.json 读取的登录邮箱
• compaction-counter — 上下文压缩次数（含 hide-when-zero）
• thinking-effort — 思考强度（low/medium/high/xhigh）
• voice-status — Voice Input 状态
• vim-mode — Vim 模式
• output-style — 当前输出风格

6.2 上下文与 Token

• context-length — 当前上下文 token 数
• context-percentage — 上下文使用百分比
• context-percentage-usable — 可用百分比（带 (u) 标识，按 u 切 used/left）
• context-bar — 上下文进度条
• context-window — 模型完整窗口大小
• tokens-input / tokens-output / tokens-total — 输入 / 输出 / 总 token
• tokens-cache-creation / tokens-cache-read — 缓存写入 / 读取 token
• input-speed / output-speed / total-speed — 三种 token 速率（窗口 0–120s 可调）

6.3 配额与限速

• block-timer — 5 小时块已用时间（含进度条 / 短条）
• reset-timer — 距下次配额重置剩余时间（可显示精确时间戳，支持时区/locale）
• weekly-usage — 7 天总用量百分比
• weekly-usage-sonnet / weekly-usage-opus — 7 天分模型用量
• weekly-reset-timer — 7 天配额重置剩余时间
• extra-usage-utilization / extra-usage-remaining — 月度 pay-as-you-go 超额使用

6.4 Git

• git-branch — 分支名（可显示为 GitHub/GitLab 可点击链接）
• git-changes — 改动统计
• git-insertions / git-deletions — 仅新增 / 仅删除
• git-status — 简短状态
• git-staged / git-unstaged / git-untracked — 各类文件计数
• git-staged-files / git-unstaged-files / git-untracked-files — 详细文件计数
• git-clean-status — 干净 / 脏标志
• git-conflicts — 冲突文件数
• git-ahead-behind — 本地 vs 远端的 ahead/behind
• git-sha — 当前 commit SHA
• git-origin-owner / git-origin-repo / git-origin-ownerrepo — origin 仓库信息
• git-upstream-owner / git-upstream-repo / git-upstream-ownerrepo — upstream 仓库
• git-is-fork — 是否 fork
• git-pr — 当前分支对应的 PR/MR（含状态、标题、可点击链接）
• git-root-dir — 仓库根目录名（可显示为 VS Code/Cursor 可点击链接）
• git-worktree-mode / git-worktree-name / git-worktree-branch / git-worktree-original-branch

6.5 系统与其它

• free-memory — 系统内存使用（Mem: 8.5G/16.0G）
• current-working-directory — CWD（可缩段数、可 ~ 缩写、fish 风格缩写）
• custom-text — 任意文本（含 emoji）
• custom-symbol — 单字符 / 图标
• custom-command — 执行任意 shell 命令并显示其 stdout
• link — OSC8 可点击链接
• skills — 当前可用技能列表（last/count/list 模式）
• separator — 手动分隔符
• flex-separator — 自适应分隔符
• time / date — 当前时间 / 日期
• truncate — 截断标记

按 a 后输入关键字、首字母缩写或模糊匹配都能找到。

七、settings.json 完整字段解析

以下面这份真实配置为例（即本文示例）：

{
  "version": 3,
  "lines": [
    [
      { "id": "1", "type": "model",          "color": "cyan" },
      { "id": "2", "type": "separator" },
      { "id": "3", "type": "context-length", "color": "brightBlack" },
      { "id": "4", "type": "separator" },
      { "id": "5", "type": "git-branch",     "color": "magenta" },
      { "id": "6", "type": "separator" },
      { "id": "7", "type": "git-changes",    "color": "yellow" }
    ],
    [
      { "type": "reset-timer" },
      { "type": "context-percentage-usable" },
      { "type": "block-timer" },
      { "type": "weekly-usage" },
      { "type": "session-usage" },
      { "type": "tokens-total" },
      { "type": "total-speed" }
    ],
    [
      { "type": "free-memory" },
      { "type": "custom-text" },
      { "type": "model" },
      { "type": "session-clock" },
      { "type": "session-cost" }
    ],
    []
  ],
  "flexMode": "full-minus-40",
  "compactThreshold": 60,
  "colorLevel": 2,
  "inheritSeparatorColors": false,
  "globalBold": false,
  "gitCacheTtlSeconds": 5,
  "minimalistMode": false,
  "powerline": {
    "enabled": false,
    "separators": [""],
    "separatorInvertBackground": [false],
    "startCaps": [],
    "endCaps": [],
    "autoAlign": false,
    "continueThemeAcrossLines": false
  }
}

顶层字段

widget 通用字段

widget 类型特有字段

举几个例子：

// Custom Text
{ "type": "custom-text", "text": "📦 my-project" }

// Custom Command
{
  "type": "custom-command",
  "commandPath": "/usr/local/bin/my-status.sh",
  "preserveColors": true,
  "timeoutMs": 1000
}

// Git Branch with link
{ "type": "git-branch", "linkMode": "github" }

// Reset Timer with timestamp
{
  "type": "reset-timer",
  "displayMode": "timestamp",
  "use24Hour": true,
  "timezone": "Asia/Shanghai",
  "locale": "zh-CN"
}

// Speed widget with rolling window
{ "type": "total-speed", "windowSeconds": 30 }

八、进阶玩法

8.1 切换 widget 的"已用 / 剩余"

Context %、Context % (usable)、Session Usage、Weekly Usage 等百分比 widget 在编辑器里按 u 在 used / left 之间切换。

• Used 模式：Ctx Used: 35%
• Left 模式：Ctx Left: 65%

8.2 短条 / 长条进度

Block Timer、Block Reset Timer、Weekly Reset Timer、Context Bar、Session Usage、Weekly Usage 都支持：

• 数字模式（Block: 3hr 45m）
• 长进度条（32 字符）
• 短进度条（16 字符，紧凑）

8.3 时间戳显示

Reset Timer / Weekly Reset Timer 可以从"剩余时间"切换到"具体重置时刻"：

• 12 / 24 制
• 自定义 IANA 时区（Asia/Shanghai、America/New_York）
• 自定义 locale

8.4 可点击链接

• Git Branch：开启 link mode 后渲染为 https://github.com/owner/repo/tree/branch
• Git Root Dir：可生成 vscode://、cursor:// 协议链接
• Link widget：任意 OSC8 链接，可在支持的终端里点击跳转

8.5 隐藏空值

许多 widget 支持 hide-when-empty / hide-when-zero：

• Git widget 在非仓库下默认显示 no git，按 h 可隐藏
• Compaction Counter 零次时可隐藏

8.6 极简模式

主菜单 → Global Overrides → 开启 Minimalist Mode。 所有 widget 强制 raw：Cost: $0.12 → $0.12，Model: Opus 4.7 → Opus 4.7。

九、Custom Command：接入外部脚本

这是 ccstatusline 的"逃生舱"——内建组件不够用？写个脚本顶上。

9.1 工作机制

每次状态栏刷新，ccstatusline 会用 shell 执行你指定的命令，把 stdout 第一行（或全部，看实现）作为显示文本。命令必须快且幂等。

9.2 添加方法

1. TUI → Lines → 选行 → a → 搜 custom command → 选中；
2. w 编辑：
   • Command Path：脚本绝对路径
   • Preserve Colors：保留 ANSI 颜色码（默认会被全局色覆盖）
   • Timeout：超时后放弃（建议 500–1000ms）

9.3 示例脚本

显示当前 PR 数（需要 gh）：

#!/usr/bin/env bash
n=$(gh pr list --author "@me" --json number | jq length 2>/dev/null)
echo "PRs: ${n:-0}"

显示 CI 状态：

#!/usr/bin/env bash
status=$(gh run list --branch "$(git branch --show-current 2>/dev/null)" \
  --limit 1 --json conclusion -q '.[0].conclusion' 2>/dev/null)
case "$status" in
  success) echo -e "\033[32mCI:✓\033[0m" ;;
  failure) echo -e "\033[31mCI:✗\033[0m" ;;
  *)       echo "CI:?" ;;
esac

显示天气：

#!/usr/bin/env bash
curl -s "wttr.in/Beijing?format=%c+%t" --max-time 1

⚠️ Custom Command 在每次刷新都会执行。把 refreshInterval 调大、给脚本加缓存（写文件 + mtime 判断），不然会拖慢状态栏并消耗资源。

9.4 颜色 ANSI 转义

如果 preserveColors: true，脚本输出的 \033[3Xm 颜色码会原样保留；否则会被 ccstatusline 的全局颜色覆盖。

十、Powerline 美化

10.1 前提

• 终端字体安装 Nerd Font（推荐 FiraCode Nerd Font、JetBrainsMono Nerd Font）
• 终端启用真彩色（基本都开了）

ccstatusline 提供自动安装 Powerline 字体的流程，需要用户同意。

10.2 启用步骤

1. TUI → Powerline Setup → 开启；
2. 选择分隔符（默认 ``）；
3. 添加 startCaps / endCaps 给整行包"胶囊"（可选）；
4. Auto-Align：多行按列对齐成报表（v2.0.8+）；
5. Continue theme across lines：多行 Powerline 颜色连续（v2.2.8+）。

10.3 自定义分隔符

支持 4–6 位 Unicode hex 直接输入（v2.1.9+），任意 Powerline 字符都行：

• E0B0 实心右箭头
• E0B1 空心右箭头
• E0B2 实心左箭头
• E0B4 圆头
• E0BC 斜杠

10.4 内建主题

Powerline Setup → Built-in Themes 提供几套预设，进去复制后改色就行。

十一、性能与缓存机制

ccstatusline 的几条关键性能优化：

11.1 Git 缓存（v2.2.16+）

• 路径：~/.cache/ccstatusline/git-cache/
• TTL：gitCacheTtlSeconds（默认 5s）
• 失效信号：检测 .git/HEAD 与 .git/index 的 mtime 变化
• Git 命令统一加 --no-optional-locks，避免与 git status 等并行命令竞争 index.lock

11.2 Block Timer 缓存（v2.0.28+）

• 路径：~/.cache/ccstatusline/block-timer-cache/
• 按配置 hash 分文件
• 5 小时块到点自动失效
• 显著减少 JSONL 全量解析

11.3 Token 去重（v2.2.12+）

流式 JSONL 中重复条目会被去重，避免高频刷新时 token 计数虚高。

11.4 子代理感知

Token speed 计算会包含 subagent 活动，让显示速度反映真实并发工作量。

11.5 终端宽度探测

• 默认通过 TTY 询问
• 嵌套 PTY / tmux 下可能失败 → 用环境变量手动覆盖：

export CCSTATUSLINE_WIDTH=200

11.6 子进程隐藏（Windows）

所有 helper 子进程设置 windowsHide，不会在 Windows 上弹额外窗口。

十二、调试与排障

12.1 手动跑 hook 流程

模拟 Claude Code 的调用：

echo '{
  "session_id": "test",
  "model": {"display_name": "Opus 4.7"},
  "cwd": "/tmp",
  "transcript_path": "/tmp/none.jsonl",
  "cost": {"total_cost_usd": 0.12},
  "context_window": {
    "context_window_size": 200000,
    "current_usage": 35000,
    "used_percentage": 17.5
  }
}' | ccstatusline

应该直接看到渲染后的状态栏字符串（带 ANSI 颜色）。

12.2 用自定义配置文件

ccstatusline --config /tmp/test-settings.json

可以同时维护多套配置实验。

12.3 hook 模式

echo '<payload>' | ccstatusline --hook

显式走 hook 分支，避免 isTTY 判断造成的歧义。

12.4 常见报错对照

12.5 强制重置

# 备份
cp ~/.config/ccstatusline/settings.json ~/ccstatusline-backup.json

# 删除配置，再次启动会以默认值重建
rm ~/.config/ccstatusline/settings.json
ccstatusline

十三、Q&A 速查

Q1：第一次跑要选 Pinned 还是 npx 版？ 长期用选 Pinned global install，不会因为远端版本变化影响行为；只是想试试选 npx。

Q2：Claude Code 底部一直没出现状态栏？ 依次检查：

1. ~/.claude/settings.json 里有 statusLine 字段；
2. which ccstatusline 能找到二进制；
3. 重启 Claude Code；
4. Refresh Interval 设小一点（5–10 秒）。

Q3：Git 信息一直是 no git？ Claude Code 的会话 cwd 不在 Git 仓库内。cwd 字段来自 Claude Code 启动时的目录，不会跟着你编辑的文件变。在仓库里启动 Claude Code。

Q4：Powerline 字符变方块/问号？ 终端字体不支持 Powerline。装 Nerd Font，或在 Powerline Setup 里关闭。

Q5：终端窄了状态栏被截断？

• 减少 widget 数量
• 启用 compactThreshold（默认 60）并选支持短模式的 widget
• 把次要信息放到第二行

Q6：终端宽度检测不准（嵌套 PTY / tmux）？

export CCSTATUSLINE_WIDTH=200

Q7：用了代理才能访问 Anthropic 用量 API？

export HTTPS_PROXY=http://your-proxy:port

usage 类组件会读这个变量（v2.2.2+）。

Q8：Claude Code 配置目录不在默认位置？

export CLAUDE_CONFIG_DIR=/custom/path/to/.claude

ccstatusline 与所有 widget 都会用这个变量。

Q9：升级 ccstatusline 时要不要先 Uninstall？ 如果当前是 npx -y ccstatusline@latest，建议先 TUI Uninstall 再切到 Pinned，避免行为漂移。本地 settings 不会被卸载流程清理。

Q10：状态栏卡？

• 调大 refreshInterval（如 15 秒）
• 减少 Custom Command 数量、给脚本加缓存
• 确认 Git 缓存开启（gitCacheTtlSeconds: 5 起）
• Block Timer 缓存自动生效，无需配置

Q11：Session Cost 没刷新？ 要求 Claude Code ≥ 1.0.85；/resume 恢复历史会话时可能不更新（Claude Code 侧的限制）。

Q12：能在 WSL 用吗？ 完全可以。Windows 详细说明见 docs/WINDOWS.md。

Q13：能在多个 Claude Code 项目用不同配置吗？ 默认共用 ~/.config/ccstatusline/settings.json。可用 --config 指定不同文件，但需要修改 Claude Code 设置里的 command：

"command": "ccstatusline --config ~/.config/ccstatusline/project-a.json"

Q14：可以同时用多种 hook（statusLine + 其它）吗？ 可以，statusLine 只是 Claude Code 众多 hook 之一，与 PreToolUse、UserPromptSubmit 等独立。详见 Claude Code 文档。

Q15：状态栏文本有 ANSI 颜色但终端不显示？

• 检查 colorLevel 不是 0
• 终端是否支持真彩色（tput colors ≥ 256）
• SSH 连接时可能丢颜色，确认 $TERM（如 xterm-256color）

Q16：怎么彻底卸载？

# TUI 里走 Uninstall（移除 settings.json 里的 statusLine）
ccstatusline
# 然后
npm uninstall -g ccstatusline
rm -rf ~/.config/ccstatusline
rm -rf ~/.cache/ccstatusline

Q17：能给 Claude Code 之外的工具用吗？ ccstatusline 是通用 stdin→stdout 状态栏渲染器。只要你能构造合法的 JSON payload pipe 进去，原则上任何工具都能集成。当然字段约定都是按 Claude Code 来的。

Q18：能贡献新 widget 吗？ 可以。项目 MIT 协议，仓库在 github.com/sirmalloc/ccstatusline。新增 widget 需要：实现 Widget 接口、注册到 widget map、加 TUI 编辑器、写测试。

Q19：本地开发怎么调试？

git clone https://github.com/sirmalloc/ccstatusline
cd ccstatusline
bun install
bun start              # 启动 TUI
bun run example        # 用示例 payload 渲染一次

Q20：状态栏数据隐私？ ccstatusline 本地运行，不会上传你的会话内容。仅在使用 weekly/session usage 等 widget 时会调用 Anthropic 用量 API（与 Claude Code 自身的 /usage 调用同源）。所有缓存在 ~/.cache/ccstatusline。

十四、备份与多机同步

14.1 需要备份的文件

~/.config/ccstatusline/settings.json          # 所有 widget 配置
~/.claude/settings.json (statusLine 字段)     # 给 Claude Code 的钩子

14.2 dotfiles 集成示例

# 在你的 dotfiles 仓库里
mkdir -p config/ccstatusline
cp ~/.config/ccstatusline/settings.json config/ccstatusline/

# 新机器恢复
mkdir -p ~/.config/ccstatusline
ln -sf "$PWD/config/ccstatusline/settings.json" ~/.config/ccstatusline/settings.json

# 再跑一次 TUI 写入 Claude Code 设置
npx -y ccstatusline@latest
# 进入 → Install → Pinned global install

14.3 多套配置切换

# 开发环境
ccstatusline --config ~/.config/ccstatusline/dev.json

# 演示模式（极简）
ccstatusline --config ~/.config/ccstatusline/demo.json

把这些命令写进 claude-dev / claude-demo 之类的 alias，按场景切换。

推荐起步配置

懒得想的话，直接照抄：

Line 1：Model | Context Length | Git Branch | Git Changes
Line 2：Block Timer | Weekly Usage | Session Cost | Session Clock

颜色建议：

• Model → cyan
• Git Branch → magenta
• Git Changes → yellow
• Weekly Usage → green
• 其余保留默认

用一周后大概率会想加：

• context-percentage-usable（防爆窗口）
• free-memory（看机器状态）
• compaction-counter（监控压缩次数）
• 自定义 Custom Command（接 CI/PR/Weather 等）

到那时你已经熟练到不用查教程了。

资源链接

• 项目主页：https://github.com/sirmalloc/ccstatusline
• npm 包：https://www.npmjs.com/package/ccstatusline
• Windows 详细文档：仓库内 docs/WINDOWS.md
• 完整用法文档：仓库内 docs/USAGE.md
• 开发文档：仓库内 docs/DEVELOPMENT.md
• 相关项目：
  • tweakcc — 自定义 Claude Code 主题/思考动词
  • ccusage — Claude Code 用量追踪
  • codachi — 状态栏宠物
  • AIWatch — 30+ AI API 实时状态监控

Happy hacking. ✨

如果你想：

• 改造你的 settings.json → 把你的需求告诉我
• 接入 Custom Command 跑某个具体脚本 → 把脚本贴出来
• 设计 Powerline 主题 → 描述你想要的视觉风格

我可以基于这份教程帮你继续往前推。