claude-code-statusline-pro

Claude Code Statusline Pro

中文 | English

使用指南

Claude Code Statusline Pro - 为Claude Code量身定制的智能状态栏系统。

✨ 核心特性

- 🎯 三大主题系统: Classic、Powerline、Capsule 主题，自适应终端能力
- 🛠️ 灵活的配置系统: 支持TOML配置文件和命令行参数覆盖
- 📊 精准Token计算: 与Claude官方API完全一致的token统计，支持渐变可视化进度条
- 🧠 智能状态识别: 基于tokens数量精准识别Thinking vs Ready状态
- 🚀 预设系统: 通过字母组合快速配置组件排布 (PMBTURS, MT, BT)
- 🌈 跨平台兼容: Windows、macOS、Linux智能适配，支持各种终端
- 🧩 多行小组件系统: 支持网格布局、静态/ API 数据源、检测与过滤器，自由扩展状态栏
- ⚡ 高性能优化: 缓存机制，300ms更新间隔，符合Claude Code官方建议
- 🌐 双语支持: 中英双语配置界面和错误提示
- 🦀 Rust 引擎: 提供原生 Rust 内核，更快更稳

🦀 Rust 重写优化亮点

- 原生 git2 仓库分析：直接获取分支、状态、stash 等信息，避免频繁 Shell 调用，在大型仓库中依然流畅
- 多层缓存体系：组件级内存缓存结合会话持久化存储，减少重复解析配置与历史数据的 IO
- Tokio 异步运行时：多线程调度渲染与文件操作，维持官方推荐的 300ms 更新节奏并提升稳定性
- 增量 Transcript 解析：按偏移量增量读取 .jsonl，并通过原子写入持久化快照，避免大型日志反复全量扫描
- 配置与扩展缓存：合并配置结果可复用并附带差异报告，多行组件缓存上次 Widget 内容以降低 I/O 和网络抖动

📋 系统要求

在开始使用之前，请确保您的系统满足以下要求：

必需条件

- Claude Code: 版本 ≥ 1.0.71
- Node.js: 版本 ≥ 16.0.0 (下载安装)
- npm: 通常随Node.js自动安装

检查当前版本

🚀 快速开始

一步配置，即刻使用

只需要在Claude Code的配置文件中添加一行配置，无需预先安装：

在项目根目录或 $USER 目录创建 .claude/settings.json：
💡 兼容说明：旧命令 npx claude-code-statusline-pro@latest 仍可继续使用，并会提示迁移。建议将现有配置更新为 npx ccsp@latest。

保存文件后，重新打开Claude Code即可看到专业版状态栏！

验证安装

打开Claude Code，你应该看到类似这样的状态栏：

🎯 快速配置指南

预设系统 - 字母组合配置

通过简单的字母组合快速定制状态栏显示内容：

- P = Project (项目名称)
- M = Model (模型信息)
- B = Branch (Git分支)
- T = Tokens (Token使用情况)
- U = Usage (使用量统计)
- R = Rate Limit (Claude.ai 订阅计划 5h / 7d 限额)
- S = Status (状态信息)

快速配置命令

注：这些命令全部是写在settings.json中的，并不是在终端直接执行使用（直接执行会打印出预览结果）

🧩 多行小组件系统

多行系统可以把状态栏扩展为网格布局，嵌入多个可独立刷新的小组件。

- 网格布局：使用 row（从1开始）和 col（从0开始）控制每个小组件的位置，支持跨行/列排布。
- 小组件类型：内置 static（静态文本）与 api（HTTP 请求）两种类型，API 小组件支持模板渲染、环境变量替换。
- 自动检测：通过 detection 段读取环境变量，可配置 equals / contains / pattern 触发条件，也可以配合 force 手动开启或关闭。
- 结果过滤：filter 支持 JSONPath + equals / contains /…