> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/sirmalloc/ccstatusline) · [上游 README](https://github.com/sirmalloc/ccstatusline/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 
              _        _             _ _            
  ___ ___ ___| |_ __ _| |_ _   _ ___| (_)_ __   ___ 
 / __/ __/ __| __/ _` | __| | | / __| | | '_ \ / _ \
| (_| (__\__ \ || (_| | |_| |_| \__ \ | | | | |  __/
 \___\___|___/\__\__,_|\__|\__,_|___/_|_|_| |_|\___|
# ccstatusline **🎨 面向 Claude Code CLI 的高度可定制状态栏格式化工具** *在终端中显示模型信息、Git 分支、Token 用量及其他指标* [![npm version](https://img.shields.io/npm/v/ccstatusline.svg)](https://www.npmjs.com/package/ccstatusline) [![npm downloads](https://img.shields.io/npm/dm/ccstatusline.svg)](https://www.npmjs.com/package/ccstatusline) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/sirmalloc/ccstatusline/blob/main/LICENSE) [![Node.js Version](https://img.shields.io/node/v/ccstatusline.svg)](https://nodejs.org) [![install size](https://packagephobia.com/badge?p=ccstatusline)](https://packagephobia.com/result?p=ccstatusline) [![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/sirmalloc/ccstatusline/graphs/commit-activity) [![Mentioned in Awesome Claude Code](https://awesome.re/mentioned-badge.svg)](https://github.com/hesreallyhim/awesome-claude-code) [![ClaudeLog - A comprehensive knowledge base for Claude](https://claudelog.com/img/claude_log_badge.svg)](https://claudelog.com/) ![Demo](https://raw.githubusercontent.com/sirmalloc/ccstatusline/main/screenshots/demo.gif)

## 📚 目录 - [最近更新](#-recent-updates) - [功能](#-features) - [本地化](#-localizations) - [快速开始](#-quick-start) - [Windows 支持](docs/WINDOWS.md) - [用法](docs/USAGE.md) - [开发](docs/DEVELOPMENT.md) - [贡献](#-contributing) - [许可证](#-license) - [相关项目](#-related-projects)
## 🆕 最近更新 ### v2.2.22 - v2.2.23 - Powerline 弹性模式、布局控制、可组合指标与更安全的配置 ![Powerline Flex Mode](https://raw.githubusercontent.com/sirmalloc/ccstatusline/main/screenshots/powerline-flex.png) - **⚡ Powerline 弹性模式** - 弹性分隔符现可在 Powerline 模式下工作，使 Powerline 状态栏能够右对齐内容或占用可用宽度。 - **🌗 按组件调暗样式** - 颜色编辑器可让整个组件或仅括号内文本变暗，重置与全部清除操作也会覆盖调暗状态。 - **🧯 更安全的设置恢复** - 无效的 `settings.json` 文件将保持原样不动，默认值在内存中渲染，状态栏会显示无效配置警告。 - **🧭 选择性 Powerline 对齐** - 在线编辑器中按 `x`，可使某个组件及其所在行的其余部分保持自然宽度，而较早的 Powerline 列仍自动对齐。 - **📏 Git 组件宽度限制** - `Git Branch` 与 `Git Root Dir` 可限制可见宽度，并以省略号安全截断，同时保留超链接目标。 - **🔣 当前目录字形** - `Current Working Dir` 可前置可选的自定义字形，包括在原始值模式下。 - **🧠 可配置的上下文回退** - 当 Claude Code 与模型名称未报告上下文窗口时，`CCSTATUSLINE_CONTEXT_SIZE_FALLBACK` 可覆盖默认的 200k 最后手段上下文窗口。 - **🧩 可组合的压缩指标** - `Compaction Counter` 可独立渲染 count、auto、manual、unknown 或 reclaimed-token 值，用于自定义布局。 - **🏷️ CLI 版本标志** - `ccstatusline --version` 现会打印已安装包版本并退出。 - **🛡️ 受保护的无效配置保存** - 当 TUI 因无效设置文件而加载了默认值时，会发出警告，并在替换该文件前要求确认。 - **🔄 用量显示与缓存修复** - 已用/剩余方向现可在所有百分比模式下正常工作，切换账户会失效缓存的用量数据，获取锁不再导致重复请求或陈旧的超时输出。 - **⏱️ 更平稳的重置计时器启动** - 在 Claude Code 内嵌的用量窗口数据尚未到达时，重置计时器会显示带标签的加载占位符，而非短暂的速率限制错误。 - **🔇 更安静的安装检测** - 尽力而为的 npm 与 Bun 探测不再将预期的包管理器错误泄漏到 TUI 中。 ### v2.2.21 - 缓存组件、压缩详情、额外用量货币与包修复 - **🔣 自定义组件字形** - Git 与 JJ 符号组件可从 TUI 覆盖或隐藏其内置字形。 - **🔁 压缩计数器详情** - `Compaction Counter` 现会统计显式的 `compact_boundary` 标记，并可选择显示触发拆分及回收的 Token。 - **💸 额外用量改进** - 新增 `Extra Usage Used`，并按用量 API 报告的计费货币格式化额外用量金额。 - **📏 自定义命令宽度上下文** - 当 ccstatusline 能检测到终端宽度时，`Custom Command` 组件会在 stdin JSON 中接收 `terminal_width`。 - **🧠 提示缓存组件** - 新增 `Cache Hit Rate`、`Cache Read` 与 `Cache Write` 组件，支持 turn/session 作用域及为空时隐藏行为。 - **🔢 Token 舍入修复** - 来自 `999950` 至 `999999` 的 Token 计数现渲染为 `1.0M`，而非 `1000.0k`。 ### v2.2.20 - 渐变、Token 精度、用量可靠性与 Git PR/MR 修复 - **🌈 渐变颜色** - 新增按组件与整行前景渐变，支持命名预设、自定义十六进制色标、TUI 选择器及 Powerline 感知渲染。在 Edit Colors 屏幕按 `g` 设置组件渐变，或在 Global Overrides 的 Override FG Color 中按 `g` 设置整行渐变。 - **🎯 更准确的 Token 计数** - `Tokens Input` 与 `Tokens Output` 现优先使用累积转录指标，再回退到上下文窗口总量。 - **💸 额外用量无限制修复** - 对于已启用超额但尚未配置月度限额的账户，额外用量组件不再卡在 `[Timeout]`。 - **🔁 压缩毛刺过滤** - `Compaction Counter` 会忽略低于 1% 的短暂上下文读数，避免不完整的状态帧产生虚假压缩计数。 - **🔀 SSH 别名 Git PR/MR 检测** - Git PR/MR 检测会解析 SSH 主机别名，同时为 CLI 选择与回退仓库链接保留规范的 GitHub 与 GitLab 主机。 - **🧪 用量测试缓存隔离** - 用量获取测试探测现会隔离 `HOME`、`USERPROFILE`、`CLAUDE_CONFIG_DIR` 及代理变量，使本地测试无法触及真实的 ccstatusline 缓存。 - **📦 依赖刷新** - 为本次发布刷新了 React/React DOM 与 Bun lockfile 开发工具解析。 ### v2.2.14 - v2.2.19 - 版本固定、npm 来源证明、用量超额组件与 Git 锁规避 - **📌 版本固定支持** - 新增对固定全局安装的支持，使 Claude Code 可持续运行特定 ccstatusline 版本。 - **🔐 npm 来源证明（provenance）认证** - 已发布包现使用可信发布来源证明，用户可验证发布构建位置，同时避免长期有效的 npm 发布 Token。 - **🔄 从自动更新安装迁移** - 若你当前使用自动更新安装，请先使用 TUI 卸载选项，再重新安装以走版本固定流程。卸载时你的 ccstatusline 设置会保留。 - **💸 额外用量组件** - 新增 Extra Usage Utilization 与 Extra Usage Remaining 组件，用于月度按量付费超额限额，空速率限制桶按零用量处理。 - **🔒 Git 锁规避** - Git 辅助工具现传递 `--no-optional-locks`，使后台状态检查避免产生 `index.lock` 竞争。 - **🧱 旧版 Git 兼容** - Git 组件避免使用较新的命令形式，使仓库状态在较旧的 Git 安装上仍可工作。 - **⚡ 持久化 Git 缓存** - Git 命令输出缓存在 `~/.cache/ccstatusline/git-cache` 下，可配置 TTL，并通过 `.git/HEAD`/`.git/index` mtime 检查减少重复的子进程工作。 - **🧭 安装流程优化** - 固定全局安装现为默认安装选项，安装与迁移流程的措辞更清晰。 - **🪟 隐藏辅助进程** - 运行时子进程设置 `windowsHide`，使辅助命令不会在 Windows 上打开额外窗口。 - **📏 终端宽度覆盖** - 当自动探测不可用时，`CCSTATUSLINE_WIDTH` 可提供显式的终端宽度。 ### v2.2.13 - 每周模型用量、语音状态、钩子与文档 - **📊 每周 Sonnet/Opus 用量小组件** - 为 Sonnet 和 Opus API 配额分别新增每周用量小组件，与 Claude Code 的 `/usage` 模型划分一致。 - **🎤 语音状态小组件** - 新增显示 Claude Code 语音输入是否启用的小组件，支持图标、文本、单词以及可选的 Nerd Font 显示模式。 - **📉 计时器短进度条** - Block Timer、Block Reset Timer 和 Weekly Reset Timer 现已支持紧凑的短进度条显示。 - **🔕 更安静的钩子输出** - 钩子处理现在会抑制无操作的 JSON 输出，使非状态更新保持静默。 ### v2.2.9 - v2.2.12 - GitLab 支持、重置计时器、上下文、压缩与 Git 小组件 - **🦊 GitLab PR/MR 支持** - `Git Branch` 和 `Git PR/MR` 现已支持 GitHub、GitLab 及兼容的自托管远程仓库，并视情况使用 `gh` 或 `glab`。 - **🔄 状态行刷新间隔** - 已安装的配置可在 TUI 中设置 Claude Code 的 `statusLine.refreshInterval`（Claude Code >=2.1.97 时支持）。 - **🧭 环绕式 TUI 导航** - 菜单/列表导航以及移动/重排模式现可在首尾项之间环绕切换。 - **📋 克隆小组件快捷键** - 在条目编辑器中按 `k` 可复制所选小组件；克隆的 Powerline 条目会获得全新的 Powerline 背景色。 - **📊 短进度条显示模式** - Context percentage、Context Bar、Session Usage、Weekly Usage、Block Timer 及重置计时器小组件可使用紧凑进度条变体。 - **⏱️ 用量时间光标** - Session Usage 和 Weekly Usage 进度条可显示当前用量窗口内的已用时间位置。 - **🕒 重置计时器时间戳** - Block 与 Weekly Reset Timer 小组件可显示精确的重置时间戳，支持紧凑格式、12/24 小时制、IANA 时区及区域设置选择。 - **🪟 Context Window 小组件** - 新增用于总模型窗口大小的 `Context Window` 小组件，使 `Context Length` 专注于当前上下文用量。 - **🔁 Compaction Counter 小组件** - 新增 `Compaction Counter` 小组件，用于跟踪会话上下文压缩次数，支持图标/文本/数字格式、可选 Nerd Font 图标，以及为零时隐藏。 - **🧮 Git 文件状态小组件** - 新增 `Git Staged Files`、`Git Unstaged Files`、`Git Untracked Files` 和 `Git Clean Status`，用于文件数量及干净/脏状态。 - **🏷️ 更清晰的上下文百分比标签** - `Context %` 和 `Context % (usable)` 在切换已用/剩余模式时，会将渲染值标注为已用或剩余。 - **⚡ 更多 Powerline 端帽** - Powerline 分隔符编辑器现支持超过三个起始/结束端帽。 - **🧠 Thinking Effort 更新** - 新增 `xhigh`；未设置 effort 时显示 `default`；未知未来 effort 级别以 `?` 标记；并跟踪实时状态 JSON 及 `/effort` 命令变更。Claude Code 在状态行数据中将 Ultracode 报告为 `xhigh`。 - **🧮 更准确的 token 计数** - 对流式重复的 JSONL 条目去重，避免 token 小组件对 Claude Code 实时输出重复计数。 - **🏷️ 更简洁的模型显示** - Model 小组件会去除 `(1M context)` 等尾部上下文后缀；若需显示总窗口大小，请使用 `Context Window`。 - **🧹 更干净的空小组件分隔符** - 手动分隔符现会在渲染为空的小组件周围折叠，避免 hide-when-empty 小组件消失后出现悬空分隔符。 - **🧱 更具韧性的 Git 辅助功能** - Git 小组件对缺失或异常的 git 命令输出采用更稳健的防御性处理。 ### v2.2.8 - Git 小组件、更智能的选择器搜索与极简模式 - **🔀 全新 Git PR 小组件** - 新增 `Git PR` 小组件，提供可点击的 PR 链接，并可选择显示当前分支的状态与标题。 - **🧰 Git 小组件大幅扩展** - 新增 `Git Status`、`Git Staged`、`Git Unstaged`、`Git Untracked`、`Git Ahead/Behind`、`Git Conflicts`、`Git SHA`、`Git Origin Owner`、`Git Origin Repo`、`Git Origin Owner/Repo`、`Git Upstream Owner`、`Git Upstream Repo`、`Git Upstream Owner/Repo`、`Git Is Fork`、`Git Worktree Mode`、`Git Worktree Name`、`Git Worktree Branch`、`Git Worktree Original Branch` 和 `Custom Symbol`。 - **👤 Claude Account Email 小组件** - 新增会话小组件，从 `~/.claude.json` 读取已登录 Claude 账户邮箱，同时遵守 `CLAUDE_CONFIG_DIR`。 - **🧼 全局极简模式（Minimalist Mode）** - 在 `Global Overrides` 中新增全局开关，强制小组件进入原始值模式，以获得更简洁、无标签的状态行。 - **🔎 更智能的小组件选择器搜索** - 添加/更换小组件选择器现支持子串、首字母缩写和模糊匹配，并提供排序结果与实时匹配高亮。 - **📏 更可靠的终端宽度检测** - 当 ccstatusline 通过包装进程或嵌套 PTY 启动时，Flex 分隔符与右对齐现可更可靠地工作。 - **🎨 Powerline 主题连续性** - 内置 Powerline 主题现可在多条状态行之间连续延伸颜色，而无需每行重新起始。
更早的更新（v2.2.6 及更早版本） ### v2.2.0 - v2.2.6 - 速度、小组件、链接与可靠性更新 - **🚀 全新 Token Speed 小组件** - 新增三个小组件：**Input Speed**、**Output Speed** 和 **Total Speed**。 - 每个速度小组件可在小组件编辑器中配置 `0-120` 秒的时间窗口（`w` 键）。 - `0` 会禁用窗口模式，改用整个会话的平均速度。 - `1-120` 会在所选滚动窗口内计算近期速度。 - **🧩 全新 Skills 小组件控件（v2.2.1）** - 新增可配置的 Skills 模式（last/count/list）、可选的 hide-when-empty 行为，以及按最近优先排序的列表大小限制。 - **🌐 Usage API 代理支持（v2.2.2）** - Usage 小组件在直接调用 Anthropic API 时会遵循大写的 `HTTPS_PROXY` 环境变量。 - **🧠 全新 Thinking Effort 小组件（v2.2.4）** - 新增显示当前 Claude Code thinking effort 级别的小组件。 - **🍎 改进 macOS 用量查询可靠性（v2.2.5）** - 提升了在 macOS 上加载 usage API token 的可靠性。 - **⌨️ 全新 Vim Mode 小组件（v2.2.5）** - 新增显示当前 vim 模式的小组件，支持 ASCII 及可选的 Nerd Font 图标显示。 - **🔗 Git 小组件链接模式（v2.2.6）** - `Git Branch` 可渲染可点击的 GitHub 分支链接，`Git Root Dir` 可为 VS Code 和 Cursor 渲染可点击的 IDE 链接。 - **🤝 更好的子代理感知速度报告** - Token 速度计算会继续纳入被引用的子代理活动，使显示速度更贴近实际并发工作。 ### v2.1.0 - v2.1.10 - Usage 小组件、链接、全新 git 插入/删除小组件与可靠性修复 - **🧩 全新 Usage 小组件（v2.1.0）** - 新增 **Session Usage**、**Weekly Usage**、**Block Reset Timer** 和 **Context Bar** 小组件。 - **📊 更准确的计数（v2.1.0）** - Usage/context 小组件在可用时会使用新的 statusline JSON 指标，以获得更准确的 token 与上下文计数。 - **🪟 Windows 空文件问题修复（v2.1.1）** - 修复了 Windows 上可能创建空 `c:\dev\null` 文件的问题。 - **🔗 全新 Link 小组件（v2.1.3）** - 新增支持可点击 OSC8 渲染、预览一致性与 raw 模式的 **Link** 小组件。 - **➕ 全新 Git Insertions 小组件（v2.1.4）** - 新增专用 Git 小组件，仅显示未提交的插入行数（例如 `+42`）。 - **➖ 全新 Git Deletions 小组件（v2.1.4）** - 新增专用 Git 小组件，仅显示未提交的删除行数（例如 `-10`）。 - **🧠 上下文格式回退修复（v2.1.6）** - 当 `context_window_size` 缺失时，上下文小组件现可从模型标识符中的长上下文标签（如 `[1m]` 和 `1M context`）推断 1M 模型。 - **⏳ 每周重置计时器拆分（v2.1.7）** - 新增独立的 `Weekly Reset Timer` 小组件。 - **⚙️ 自定义配置文件标志（v2.1.8）** - 新增 `--config ` 支持，使 ccstatusline 可从自定义文件位置加载/保存设置。 - **🔣 Unicode 分隔符十六进制输入升级（v2.1.9）** - Powerline 分隔符十六进制输入现支持 4-6 位数字（完整 Unicode 码点最高至 `U+10FFFF`）。 - **🌳 裸仓库 worktree 检测修复（v2.1.10）** - `Git Worktree` 现可正确检测由裸仓库创建的关联 worktree。
### v2.0.26 - v2.0.29 - 性能、Git 内部机制与工作流程改进 - **🧠 内存使用（Memory Usage）组件 (v2.0.29)** - 新增组件，显示当前系统内存使用情况（`Mem: used/total`）。 - **⚡ Block timer 缓存 (v2.0.28)** - 缓存 block timer 指标，减少每次渲染时的 JSONL 解析；按配置生成哈希缓存文件，并自动在 5 小时 block 后失效。 - **🧱 Git 组件命令重构 (v2.0.28)** - 重构 Git 组件以使用共享的 Git 命令辅助函数，并扩大失败与边界情况的测试覆盖。 - **🪟 Windows UTF-8 管道输出修复 (v2.0.28)** - 为管道传输的状态行渲染设置 Windows UTF-8 代码页。 - **📁 Git 根目录（Git Root Dir）组件 (v2.0.27)** - 新增 Git 组件，显示仓库根目录名称。 - **🏷️ 会话名称（Session Name）组件 (v2.0.26)** - 新增组件，从 `/rename` 显示当前 Claude Code 会话名称。 - **🏠 当前工作目录（Current Working Directory）主目录缩写 (v2.0.26)** - 为预览与实时渲染中的 CWD 显示新增 `~` 缩写选项。 - **🧠 Context 模型后缀修复 (v2.0.26)** - Context 组件现可跨模型识别 `[1m]` 后缀，而非仅支持单一模型路径。 - **🧭 组件选择器 UX 更新 (v2.0.26)** - 改进组件发现与导航，并添加更清晰、更安全的清行行为。 - **⌨️ TUI 编辑器输入修复 (v2.0.26)** - 防止快捷键/输入泄漏到组件编辑器流程中。 - **📄 仓库文档更新 (v2.0.26)** - 将指引从 `CLAUDE.md` 迁移至 `AGENTS.md`（兼容符号链接）。 ### v2.0.16 - 为当前工作目录组件添加 fish 风格路径缩写开关 ### v2.0.15 - Block Timer 计算修复 - 修复 block timer 中的计算错误 ### v2.0.14 - 为 Context Percentage 组件添加剩余模式开关 - **剩余模式（Remaining Mode）** - 在 TUI 中配置时，可按 `u` 键在 Context Percentage 组件的使用百分比与剩余百分比之间切换。 ### v2.0.12 - 自定义文本（Custom Text）组件现支持 emoji - **👾 Emoji 支持** - 现可将 emoji 粘贴到自定义文本组件中。也可开启合并选项，为组件添加 emoji 标签，效果如下： ![Emoji Support](https://raw.githubusercontent.com/sirmalloc/ccstatusline/main/screenshots/emojiSupport.png) ### v2.0.11 - 无限制状态行 - **🚀 无行数限制** - 可按需配置任意数量的状态行，已移除 3 行限制 ### v2.0.10 - Git 更新 - **🌳 Git Worktree 组件** - 使用 git worktree 时显示当前活跃的 worktree 名称 - **👻 隐藏「no git」消息开关** - Git 组件现支持在非仓库环境中隐藏「no git」消息（编辑组件时按 `h` 键切换） ### v2.0.8 - Powerline 自动对齐 ![Powerline Auto-Alignment](https://raw.githubusercontent.com/sirmalloc/ccstatusline/main/screenshots/autoAlign.png) - **🎯 组件对齐** - 在 Powerline 模式下跨多条状态行自动对齐组件，实现整洁的列式布局（在 Powerline 设置中按 `a` 切换） ### v2.0.7 - 当前工作目录与会话费用 ![Current Working Directory and Session Cost](https://raw.githubusercontent.com/sirmalloc/ccstatusline/main/screenshots/cwdAndSessionCost.png) - **📁 当前工作目录（Current Working Directory）** - 显示当前工作目录，支持可配置的路径段显示 - 设置显示的路径段数量（例如仅显示最后 2 段：`.../Personal/ccstatusline`） - 支持原始值模式以实现紧凑显示 - 自动用省略号截断过长路径 - **💰 会话费用（Session Cost）组件** - 追踪 Claude Code 会话费用（需要 Claude Code 1.0.85+） - 以 USD 显示会话总费用 - 支持原始值模式（仅显示 `$X.YZ` 与 `Cost: $X.YZ`） - 基于 Claude Code 会话数据实时追踪费用 - 注意：使用 `/resume` 时费用可能无法正确更新（Claude Code 限制） - **🐛 错误修复** - 修复 Block Timer 计算，确保跨 block 边界的时间追踪准确 - 改进组件编辑器稳定性，正确处理 Ctrl+S - 增强数字输入字段中的光标显示 ### v2.0.2 - Block Timer 组件 ![Block Timer](https://raw.githubusercontent.com/sirmalloc/ccstatusline/main/screenshots/blockTimerSmall.png) - **⏱️ Block Timer** - 追踪你在 5 小时 Claude Code block 中的进度 - 以小时/分钟显示当前 block 已用时间（例如「3hr 45m」） - 进度条模式显示可视化完成百分比 - 两种进度条样式：全宽（32 字符）或紧凑（16 字符） - 根据转录时间戳自动检测 block 边界 ### v2.0.0 - Powerline 支持与增强主题 - **⚡ Powerline 模式** - 美观的 Powerline 风格状态行，带箭头分隔符与可自定义端帽 - **🎨 内置主题** - 多个预配置主题，可复制并自定义 - **🌈 高级颜色支持** - 基础（16 色）、256 色（支持自定义 ANSI 代码）与真彩色（支持十六进制代码）模式，以及多停靠点**渐变**（按组件或整行） - **🔗 组件合并** - 可将多个组件合并，支持有/无内边距，实现无缝设计 - **📦 简易安装** - 可直接通过 `npx` 或 `bunx` 安装，无需全局包 - **🔤 自定义分隔符** - 可添加多个 Powerline 分隔符，支持自定义十六进制代码以适配字体 - **🚀 自动字体安装** - 经用户同意后自动安装 Powerline 字体
## ✨ 功能特性 - **📊 实时指标** - 显示模型名称、git 分支、token 用量、各模型周用量、额外用量限制、语音输入状态、会话时长、压缩次数、block timer 等 - **🎨 完全可定制** - 选择显示内容并为每个元素自定义颜色 - **⚡ Powerline 支持** - 美观的 Powerline 风格渲染，带箭头分隔符、端帽与自定义字体 - **📐 多行支持** - 可配置多条独立状态行 - **🖥️ 交互式 TUI** - 基于 React/Ink 的内置配置界面 - **🔎 快速组件选择器** - 按分类添加/更换组件，支持搜索与排序匹配 - **⚙️ 全局选项** - 在所有组件间应用一致的格式（内边距、分隔符、粗体、极简模式与颜色覆盖） - **🚀 跨平台** - 与 Bun 和 Node.js 无缝配合 - **🔧 灵活配置** - 通过 `CLAUDE_CONFIG_DIR` 环境变量支持自定义 Claude Code 配置目录 - **📏 智能宽度检测** - 通过弹性分隔符自动适配终端宽度 - **⚡ 零配置** - 合理的默认设置，开箱即用
## 🌐 本地化 本节中的本地化版本为在本仓库之外维护的第三方 fork，未经本仓库维护、审核或背书，使用前请自行审查其代码与发布版本。 - 🌏 **中文版 (Chinese):** [ccstatusline-zh](https://github.com/huangguang1999/ccstatusline-zh)
## 🚀 快速开始 ### 无需安装！可直接通过 npx 或 bunx 使用： ```bash # Run the configuration TUI with npm npx -y ccstatusline@latest # Or with Bun (faster) bunx -y ccstatusline@latest ``` 两条命令启动相同的 TUI。在初始设置流程中，若希望 Claude Code 固定在你正在运行的 ccstatusline 版本而非跟随 `@latest`，请选择 **Pinned global install（固定全局安装）**；TUI 将通过 npm 或 Bun 全局安装该版本，并将固定的 `ccstatusline` 命令写入 Claude Code 设置。固定安装后，日后可直接运行 `ccstatusline` 启动 TUI。
配置 ccstatusline 交互式配置工具提供终端 UI，你可以： - 配置多条独立状态行 - 添加/移除/重排状态行组件 - 为每个组件自定义颜色 - 配置弹性分隔符行为 - 在支持时配置 Claude Code 状态行刷新间隔 - 编辑自定义文本组件 - 安装/卸载到 Claude Code 设置 - 实时预览状态行 > 💡 **提示：** 你的设置会自动保存到 `~/.config/ccstatusline/settings.json` > 🔧 **自定义 Claude 配置：** 如果你的 Claude Code 配置位于非标准路径，请设置 `CLAUDE_CONFIG_DIR` 环境变量： > ```bash > # Linux/macOS > export CLAUDE_CONFIG_DIR=/custom/path/to/.claude > ``` > 🌐 **Usage API 代理：** Usage 小组件在直接调用 Anthropic API 时会遵循大写的 `HTTPS_PROXY` 环境变量。 > 🪟 **Windows 支持：** PowerShell 示例、安装说明、字体、故障排除、WSL 以及 Windows Terminal 配置请参见 [docs/WINDOWS.md](docs/WINDOWS.md)。
Claude Code settings.json 格式 从 TUI 安装时，ccstatusline 会向你的 Claude Code 设置写入一个 `statusLine` 命令对象： ```json { "statusLine": { "type": "command", "command": "npx -y ccstatusline@latest", "padding": 0, "refreshInterval": 10 } } ``` 仅当你的 Claude Code 版本支持时（>=2.1.97）才会写入 `refreshInterval`。TUI 可将其设置为 `1-60` 秒，或将输入留空以移除该项。 其他支持的 command 值包括： - `bunx -y ccstatusline@latest` - `ccstatusline`（适用于自管/全局安装） 对于固定版本安装，请使用 `npx -y ccstatusline@latest` 或 `bunx -y ccstatusline@latest` 启动 TUI，然后选择 **Pinned global install**。TUI 会通过全局安装当前活动版本，并将 `"command": "ccstatusline"` 写入 `settings.json` 来固定版本；之后，你可以直接运行 `ccstatusline` 直接打开 TUI。
## 🤝 参与贡献 欢迎贡献！请随时提交 Pull Request。 1. Fork 该仓库 2. 创建你的功能分支（`git checkout -b feature/amazing-feature`） 3. 提交你的更改（`git commit -m 'Add some amazing feature'`） 4. 推送到该分支（`git push origin feature/amazing-feature`） 5. 打开 Pull Request ## 支持 如果 ccstatusline 对你有帮助，欢迎请作者喝杯咖啡： Buy Me A Coffee ## 📄 许可证 [MIT](LICENSE) © Matthew Breedlove ## 👤 作者 **Matthew Breedlove** - GitHub: [@sirmalloc](https://github.com/sirmalloc) ## 🔗 相关项目 - [ccstatusline-editor](https://github.com/refinist/ccstatusline-editor) - 用于构建 ccstatusline 配置的可视化编辑器——拖拽、预览、发布。 - [tweakcc](https://github.com/Piebald-AI/tweakcc) - 自定义 Claude Code 主题、thinking verbs 等。 - [ccusage](https://github.com/ryoppippi/ccusage) - 跟踪并展示 Claude Code 使用指标。 - [codachi](https://github.com/vincent-k2026/codachi) - 随上下文窗口增长而成长的电子宠物风格 statusline 伙伴。 - [AIWatch](https://ai-watch.dev) - 30+ 个 AI API 与应用的实时状态监控；可与 Custom Command 小组件配合，在 status line 中展示提供商故障。 - [crispy-recall](https://github.com/TheSylvester/crispy-recall) - 为 Claude Code 与 Codex 会话提供可搜索的记忆。本地、快速、无需守护进程。 ## 🙏 致谢 - 为配合 [Claude Code CLI](https://claude.ai/code) by Anthropic 使用而构建 - 终端 UI 由 [Ink](https://github.com/vadimdemedes/ink) 驱动 - 为 Claude Code 社区倾心打造 ❤️
## Star History Star History Chart
### 🌟 表达你的支持 如果这个项目对你有帮助，请给个 ⭐！ [![GitHub stars](https://img.shields.io/github/stars/sirmalloc/ccstatusline?style=social)](https://github.com/sirmalloc/ccstatusline/stargazers) [![GitHub forks](https://img.shields.io/github/forks/sirmalloc/ccstatusline?style=social)](https://github.com/sirmalloc/ccstatusline/network/members) [![GitHub watchers](https://img.shields.io/github/watchers/sirmalloc/ccstatusline?style=social)](https://github.com/sirmalloc/ccstatusline/watchers) [![npm version](https://img.shields.io/npm/v/ccstatusline.svg)](https://www.npmjs.com/package/ccstatusline) [![npm downloads](https://img.shields.io/npm/dm/ccstatusline.svg)](https://www.npmjs.com/package/ccstatusline) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/sirmalloc/ccstatusline/blob/main/LICENSE) [![Made with Bun](https://img.shields.io/badge/Made%20with-Bun-000000.svg?logo=bun)](https://bun.sh) [![Issues](https://img.shields.io/github/issues/sirmalloc/ccstatusline)](https://github.com/sirmalloc/ccstatusline/issues) [![Pull Requests](https://img.shields.io/github/issues-pr/sirmalloc/ccstatusline)](https://github.com/sirmalloc/ccstatusline/pulls) [![Contributors](https://img.shields.io/github/contributors/sirmalloc/ccstatusline)](https://github.com/sirmalloc/ccstatusline/graphs/contributors) ### 💬 联系 [Report Bug](https://github.com/sirmalloc/ccstatusline/issues) · [Request Feature](https://github.com/sirmalloc/ccstatusline/issues) · [Discussions](https://github.com/sirmalloc/ccstatusline/discussions)