🎨 Claude Code CLI 高度可定制状态栏格式化工具 — 中文汉化版

在终端中显示模型信息、Git 分支、Token 用量及其他实时指标

本项目是 ccstatusline 的中文汉化 Fork，当前同步至上游 v2.2.19 版本（含 Voice Status、版本固定全局安装、Jujutsu VCS、CompactionCounter、超额用量组件、Git 子进程缓存等最新功能）。所有用户可见的界面文本（组件名称、分类、描述、菜单标签、提示信息等）均已翻译为中文，方便中文用户使用。

• 关于本项目
• 功能特性
• 快速开始
• Windows 支持
• 使用方法
• 可用组件
• 配置界面（TUI）
• API 文档
• 开发指南
• 致谢
• 许可证

ccstatusline-zh 是 ccstatusline 的中文汉化版本。

ccstatusline 是一个优秀的 Claude Code CLI 状态栏格式化工具，支持 50+ 种可定制组件、Powerline 主题、交互式 TUI 配置界面等丰富功能。本项目在其基础上，将所有用户可见的英文文本直接替换为中文，包括：

• 72 个组件的名称、描述、分类标签（含 v2.2.13 新增的 Voice Status / 周 Sonnet 用量 / 周 Opus 用量，v2.2.17 新增的超额用量占比 / 超额用量剩余）
• TUI 配置界面的全部菜单项、帮助文本、提示信息、对话框
• 布局组件（分隔符、弹性分隔符）的名称和描述
• 极简模式 / Minimalist Mode、模糊搜索组件选择器、Powerline 主题色延续（v2.2.8）
• 上下文窗口、Git 文件状态系列（已暂存 / 未暂存 / 未跟踪 / 干净）、短条形百分比模式、GitLab 支持、Reset Timer 时区/IANA 选择、TUI 环绕导航、refreshInterval 配置（v2.2.10）
• Jujutsu VCS 系列（书签 / 工作区 / 根目录 / 变更 / 增删 / 描述 / 修订）、CompactionCounter 压缩计数、用量时间游标、Reset Timer 绝对时间戳、Powerline 端帽数量解锁、思考力度组件 xhigh 等级（v2.2.12）
• Voice Status 语音状态组件、周 Sonnet / 周 Opus 用量组件、Timer 短进度条、Hook 输出静默（v2.2.13）
• 版本固定全局安装（Pinned global install）、管理安装 / 检查更新菜单、npm 仓库更新检测、固定安装版本不一致防错屏幕（v2.2.14–v2.2.16）
• 超额用量占比 / 超额用量剩余组件（按量付费月度超额额度，支持禁用时隐藏）、用量 API 空值桶兼容、Git 命令旧版本兼容与 --no-optional-locks 锁规避（v2.2.17–v2.2.18）
• Git 子进程输出持久化缓存（可配置 TTL，按 .git/HEAD / .git/index mtime 失效）、CCSTATUSLINE_WIDTH 终端宽度覆盖、固定全局安装设为默认安装项、Windows 隐藏辅助进程窗口（v2.2.19）
• 确认对话框 "是 / 否"
• 分类筛选 "全部" 等界面元素

内部标识符（如 settings.json 中的 widget type ID "model"、"git-branch" 等）保持英文不变，确保与上游版本的配置文件完全兼容。

• 50+ 种可定制组件 — 模型、Git（含 PR / 冲突 / 暂存 / Origin / Upstream / 工作树等细分组件）、Token、上下文、会话、费用、速度等
• 交互式 TUI 配置 — 按 ccstatusline-zh setup 启动可视化配置界面
• Powerline 风格 — 内置多款 Powerline 主题，支持自定义分隔符，支持主题色跨行延续
• 极简模式 — 一键让所有组件切换到"无标签"模式，状态栏更精简
• 模糊搜索组件 — 添加组件时支持子串 / 首字母 / 模糊匹配，带实时高亮
• Claude 账户邮箱 — 状态栏显示当前登录的 Claude 账户邮箱
• 多行布局 — 支持多行状态栏配置
• 实时预览 — 配置时即时预览效果
• 自定义颜色 — 每个组件支持独立的前景色和背景色设置
• 自定义命令 & 文本 & 符号 — 可嵌入自定义 Shell 命令输出、静态文本或单字符符号/Emoji
• 可点击链接 — 支持 OSC8 终端超链接（Git 分支、Git PR、仓库根目录等可配置）
• 跨平台 — 支持 macOS、Linux、Windows

通过 npm 全局安装：

npm install -g ccstatusline-zh

或者使用 Bun：

bun install -g ccstatusline-zh

💡 提示：v2.2.14 起 ccstatusline 增加了「固定版本全局安装」选项，TUI 中选择 固定全局安装 即可锁定当前版本，避免 @latest 跟随上游。详见 TUI 安装流程。

在 Claude Code 设置中添加状态栏配置。编辑 ~/.claude/settings.json：

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

如果使用 npx 或 bunx 运行，可以使用以下命令：

{
  "statusLine": {
    "type": "command",
    "command": "npx -y ccstatusline-zh@latest",
    "padding": 0
  }
}

refreshInterval 仅在 Claude Code ≥ 2.1.97 时生效，TUI 中可设置为 1-60 秒，留空则不写入该字段。

其他支持的 command 取值：

• bunx -y ccstatusline-zh@latest
• ccstatusline-zh（用于自管理 / 全局安装）

如需固定版本，可在 TUI 安装时选择「固定全局安装」，TUI 会全局安装当前版本并将 command 写为 ccstatusline-zh。

ccstatusline-zh setup

这将打开交互式 TUI 配置界面，你可以：

• 添加、删除、重新排列组件
• 设置颜色和样式
• 选择 Powerline 主题
• 实时预览状态栏效果

ccstatusline-zh 完整支持 Windows 系统。安装方式相同：

npm install -g ccstatusline-zh

Windows 下 Claude Code 的配置路径为 %USERPROFILE%\.claude\settings.json。

安装并配置 statusLine 后，ccstatusline-zh 会在每次 Claude Code 更新状态时自动运行。状态数据通过 stdin 以 JSON 格式传入。

cat scripts/payload.example.json | ccstatusline-zh

ccstatusline-zh --config /path/to/custom-settings.json

运行 ccstatusline-zh setup 打开交互式配置界面。

• 编辑状态栏 — 添加、删除、移动、配置组件
• Powerline 设置 — 选择主题和自定义分隔符
• 全局样式覆盖 — 设置全局颜色和样式
• 终端选项 — 配置终端宽度和颜色级别
• 配置状态行 — 配置 Claude Code 状态行刷新间隔（Claude Code ≥ 2.1.97）
• 安装到 Claude Code — 选择自动更新 / 固定全局安装两种方式
• 管理安装 — 已固定安装时可检查 npm 更新、运行全局更新命令、卸载
• 检查更新 — 查询 npm 仓库最新版本并对比当前版本

详细的 API 文档和 JSON Payload 格式说明请参考上游项目：

👉 ccstatusline API Documentation

• Bun >= 1.0
• Node.js >= 14.0.0

# 克隆仓库
git clone https://github.com/huangguang1999/ccstatusline-zh.git
cd ccstatusline-zh

# 安装依赖
bun install

# 运行示例
bun run example

# 启动 TUI
bun run start setup

# 构建
bun run build

# 代码检查
bun run lint

src/
├── ccstatusline.ts          # 入口文件
├── widgets/                 # 组件目录（72 个组件）
│   ├── Model.ts
│   ├── GitBranch.ts
│   ├── TokensInput.ts
│   ├── shared/              # 共享工具函数
│   └── ...
├── tui/                     # TUI 配置界面
│   ├── App.tsx
│   └── components/          # 界面组件
├── utils/                   # 工具函数
└── types/                   # 类型定义

• ccstatusline — 原始项目，由 sirmalloc 开发维护
• Claude Code — Anthropic 的 CLI 编码助手
• Ink — React 终端渲染框架

本项目遵循 MIT 许可证，与上游项目保持一致。