_        _             _ _            
  ___ ___ ___| |_ __ _| |_ _   _ ___| (_)_ __   ___ 
 / __/ __/ __| __/ _` | __| | | / __| | | '_ \ / _ \
| (_| (__\__ \ || (_| | |_| |_| \__ \ | | | | |  __/
 \___\___|___/\__\__,_|\__|\__,_|___/_|_|_| |_|\___|
                                                     

📚 目录

• 最近更新
• 功能特性
• 多语言支持
• 快速开始
• Windows 支持
• 使用方法
• 开发指南
• 参与贡献
• 许可证
• 相关项目

🆕 最近更新

v2.2.28 - v2.2.29 - 服务健康状态、灵活格式与弹性渲染

• 🩺 Claude service health - 新增 Claude Status 组件，支持实时严重程度、带缓存的 48 小时事件历史条、过期数据回退，并在状态数据不可用时优雅地显示 ?。
• 🙈 统一条件隐藏 - 数字、Git、JJ、用量、缓存及其他组件现共享同一个 h 检查清单，用于受支持的隐藏条件；现有设置将自动迁移，并可选择对装饰性文本或符号进行合并目标隐藏。
• 🔢 可配置数字格式 - 数字组件可按组件，或按 token、速度、百分比、内存和成本类型全局使用精确、紧凑或整数样式；高级配置还可显式设置小数精度。
• 📜 更快、更可靠的大会话渲染 - 基于会话记录的 token、时长、速度、压缩、effort 和会话名称指标现在通过一次共享扫描流式处理 JSONL 记录，而不是将整个会话记录加载为单个字符串；无活动块的结果会被短暂缓存，以避免重复扫描完整历史。
• ⚠️ Git 冲突显示控制 - Git Conflicts 可在计数为零时隐藏，或在无冲突时显示 ⚠0 或可自定义的洁净符号。
• 🩹 自愈式用量锁 - 用量组件会忽略超过 24 小时后的不可执行获取锁截止时间，使因时钟跳变或旧测试产物导致的异常锁在下次渲染时恢复。
• 🧹 有界 Git 缓存清理 - 持久化 Git 缓存写入失败时会清理对应临时文件，并复用一个稳定的回退名称，防止 Windows 文件锁泄漏出成千上万个孤立临时文件。
• 📊 一致的计时器进度条 - Block Timer、Block Reset Timer 和 Weekly Reset Timer 现在会将进度条填充四舍五入到最近的单元格，与其他进度组件保持一致。

v2.2.27 - 可移植配置导入与导出

• 📦 配置导入/导出 - 将当前 TUI 配置导出为 JSON，校验并预览导入内容，然后替换所有设置或仅合并所提供的字段，同时保留本地安装元数据，并将结果保持未保存状态以便审核。

v2.2.25 - v2.2.26 - Fable 用量、已迁移的用量 API 支持、压缩精度与渲染可靠性

• 🪄 每周 Fable 用量 - 新增 Weekly Fable Usage 小组件，支持百分比、进度条、剩余模式与时间光标控制。
• 📊 重新调整用量 API 支持 - 会话和全部模型的每周用量可回退到新的 limits[] 响应，而 Sonnet、Opus 和 Fable 的每周用量小组件会读取权威的 weekly_scoped 条目，确保迁移账户不会显示过期或冻结的数值。
• 🧠 修正压缩后的上下文状态 - 在 /compact 后，上下文长度和百分比小组件会立即根据 compact_boundary.postTokens 重置，然后切换到首个新轮次，而不是保留压缩前的长度。
• 🧹 隐藏小组件分隔符更可靠 - 手动分隔符现在会跳过渲染为空的小组件，保留预期的可见边界，并继承实际前一个可见小组件的颜色。
• ⚡ 非阻塞的 Git PR/CI 刷新 - Git PR 和 CI 小组件会从带版本号的磁盘缓存渲染，同时在后台刷新过期数据，避免缓慢的 gh 调用阻塞状态栏。

v2.2.22 - v2.2.24 - Powerline 弹性模式、缓存/CI/沙箱可见性、布局控制、可组合指标与更安全的配置

• ⏳ Prompt 缓存计时器 - 新增 Cache Timer 小组件，支持实时 HOT 状态、TTL 倒计时、可配置的 5 分钟/1 小时窗口，以及可自定义的状态字形。
• ✅ GitHub CI 状态 - 新增 Git CI Status 小组件，用于汇总当前分支 Pull Request 中失败、待处理和成功的检查。
• 🔒 沙箱状态 - 新增 Sandbox Status 小组件，支持字形、文本和 Nerd Font 格式，并在每次刷新时跟随 Claude Code 的分层沙箱设置。
• ↔️ 单侧默认内边距 - 现在，标准布局和 Powerline 布局中的默认小组件内边距可设置为两侧、仅左侧或仅右侧。
• ⚡ 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 可为自定义布局独立渲染计数、自动、手动、未知或已回收 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 现在优先使用累积的 transcript 指标，然后再回退到上下文窗口总量。
• 💸 额外用量无上限修复 - 对于已启用超额用量但未配置月度限额的账户，额外用量组件不再卡在 [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 锁文件中的开发工具依赖解析。

v2.2.14 - v2.2.19 - 版本固定、npm 溯源证明、超额用量组件以及避免 Git 锁

• 📌 版本固定支持 - 新增对固定版本全局安装的支持，使 Claude Code 可以继续使用指定 ccstatusline 版本运行。
• 🔐 npm 溯源证明 - 已发布的软件包现在采用可信发布溯源证明，用户可验证各发行版的构建来源，同时避免使用长期有效的 npm 发布令牌。
• 🔄 从自动更新安装迁移 - 如果你当前使用自动更新安装，请先使用 TUI 卸载选项，然后重新安装以进入版本固定流程。卸载时会保留你的 ccstatusline 设置。
• 💸 额外用量组件 - 新增“额外用量使用率”和“额外用量剩余”组件，用于月度按量计费超额限制，空值速率限制桶按零用量处理。
• 🔒 避免 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 显示模式。
• 📉 计时器短进度条 - 块计时器、块重置计时器和每周重置计时器现在支持紧凑的短进度条显示。
• 🔕 更安静的钩子输出 - 钩子处理现在会抑制空操作 JSON 输出，使非状态更新保持静默。

v2.2.9 - v2.2.12 - 支持 GitLab、重置计时器、上下文、压缩及 Git 组件

• 🦊 GitLab PR/MR 支持 - Git Branch 和 Git PR/MR 现在支持 GitHub、GitLab 以及兼容的自托管远程仓库，并按需使用 gh 或 glab。
• 🔄 状态栏刷新间隔 - 当 Claude Code >=2.1.97 支持该功能时，已安装的配置可通过 TUI 设置 Claude Code 的 statusLine.refreshInterval。
• 🧭 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，用于显示文件数量以及 clean/dirty 状态。
• 🏷️ 更清晰的上下文百分比标签 - 在切换已用/剩余模式时，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。
• 🧹 更整洁的空组件分隔符 - 手动分隔符现在会在渲染为空的组件周围自动收起，避免在“空时隐藏”组件消失后遗留悬挂分隔符。
• 🧱 更健壮的 Git 辅助功能 - Git 组件能更稳妥地处理缺失或异常的 git 命令输出。

✨ 特性

• 📊 实时指标 - 显示模型名称、git 分支、token 用量、Sonnet/Opus/Fable 每周用量、额外用量限制、语音输入状态、会话时长、压缩次数、区块计时器等
• 🎨 完全可自定义 - 选择要显示的内容，并为每个元素自定义颜色
• ⚡ Powerline 支持 - 美观的 Powerline 风格渲染，支持箭头分隔符、端帽和自定义字体
• 📐 多行支持 - 配置多个独立状态栏
• 🖥️ 交互式 TUI - 使用 React/Ink 构建的内置配置界面
• 🔎 快速组件选择器 - 按类别添加/更改组件，支持搜索和按相关度排序匹配
• ⚙️ 全局选项 - 在所有组件中应用一致格式（内边距、分隔符、粗体、极简模式以及颜色覆盖）
• 📦 可移植配置 - 将设置导出为 JSON，并预览替换或合并导入，便于备份和共享
• 🚀 跨平台 - 在 Bun 和 Node.js 下均能无缝运行
• 🔧 灵活配置 - 通过 CLAUDE_CONFIG_DIR 环境变量支持自定义 Claude Code 配置目录
• 📏 智能宽度检测 - 通过弹性分隔符自动适配终端宽度
• ⚡ 零配置 - 开箱即用的合理默认设置

🌐 本地化

本节的本地化版本均为第三方派生仓库，在本仓库之外独立维护。本仓库不对其进行维护、审核或背书，因此在使用前，请先审查其代码与发布版本。

• 🌏 中文版 (Chinese): ccstatusline-zh

🚀 快速开始

无需安装！可直接通过 npx 或 bunx 使用：

# 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。

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

🤝 贡献

欢迎参与贡献！请随时提交 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 对您有帮助，请考虑请我喝杯咖啡：

📄 License

MIT © Matthew Breedlove

👤 Author

Matthew Breedlove

• GitHub: @sirmalloc

🔗 Related Projects

• ccstatusline-editor - 用于构建 ccstatusline 配置的可视化编辑器——拖拽、放置、预览、发布。
• tweakcc - 自定义 Claude Code 主题、思考动词以及更多。
• ccusage - 跟踪并展示 Claude Code 用量指标。
• ccsidekick - 带有动态角色的 Claude Code 状态栏，并附带费用、git 和用量组件。
• codachi - 一只电子宠物风格的状态栏宠物，会随着你的上下文窗口成长。
• AIWatch - 30+ AI API 与应用的实时状态监控；可配合 Custom Command widget 在状态栏中显示服务商故障。
• ccsessions - Claude Code 命令行会话管理器；包含 cc-session-num，一个 Custom Command widget，用于显示当前会话的排名（#1、#2、…）。
• crispy-recall - 为 Claude Code 和 Codex 会话提供可搜索的记忆。本地运行、快速、无需守护进程。
• statuslin.es - Claude Code 状态栏社区展示库，提供实时、沙盒渲染的预览。
• claude-carbon - 为你的 Claude Code 会话显示实时 CO2 估算，与费用并列展示。提供 --segment 模式，专为嵌入 Custom Command widget 而设计。
• claudenews - 在代理工作时，于状态栏中推送开发者新闻：Hacker News、GitHub Trending 以及按语言分类的信息源，支持可选翻译与简短摘要。提供 --segment 模式，专为嵌入 Custom Command widget 而设计。

🙏 Acknowledgments

• 专为 Anthropic 的 Claude Code CLI 打造
• 终端 UI 由 Ink 驱动
• 以 ❤️ 为 Claude Code 社区制作

星标历史