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版本
claude --version

# 检查Node.js版本
node --version

# 检查npm版本
npm --version

🚀 快速开始

一步配置，即刻使用

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

在项目根目录或 $USER 目录创建 .claude/settings.json：

{
  "statusLine": {
    "type": "command", 
    "command": "npx ccsp@latest"
  }
}

💡 兼容说明：旧命令 npx claude-code-statusline-pro@latest 仍可继续使用，并会提示迁移。建议将现有配置更新为 npx ccsp@latest。

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

验证安装

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

📁 my-project | 🤖 S4 | 🌿 main | 📊 [████████████░░░] 80.1%(160k/200k) | $21.07 | ✅ Ready

🎯 快速配置指南

预设系统 - 字母组合配置

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

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

快速配置命令

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

# 显示所有组件（推荐）
npx ccsp@latest --preset PMBTURS --theme powerline

# 只显示模型、Token和使用量
npx ccsp@latest --preset MTU --theme classic

# 只显示分支和Token信息
npx ccsp@latest --preset BT --theme capsule

🧩 多行小组件系统

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

• 网格布局：使用 row（从1开始）和 col（从0开始）控制每个小组件的位置，支持跨行/列排布。
• 小组件类型：内置 static（静态文本）与 api（HTTP 请求）两种类型，API 小组件支持模板渲染、环境变量替换。
• 自动检测：通过 detection 段读取环境变量，可配置 equals / contains / pattern 触发条件，也可以配合 force 手动开启或关闭。
• 结果过滤：filter 支持 JSONPath + equals / contains / pattern 匹配，只在命中关键字时刷新；可用于最近请求等场景。
• 模板示例：项目内提供 configs/components/usage.template.toml 与 configs/components/rate_limit.template.toml，复制到 ~/.claude/statusline-pro/components/ 后按需改写。

快速启用

在 config.toml 中开启多行模式并指定要加载的组件文件：

[multiline]
enabled = true

执行 npx ccsp@latest config init -w 可以一次性生成主配置并复制所有小组件模板。

🎨 三大主题系统

Classic 主题 - 最大兼容性

Classic主题支持三种图标模式，默认会根据终端能力自动选择：

🎯 Nerd Font 模式（推荐）

需要安装Nerd Font字体，并在对应的终端中选择使用字体，推荐使用 Hack Nerd Font

😊 Emoji 模式

适合支持Emoji但没有Nerd Font的终端

📝 文本模式

最大兼容性，适合所有终端环境

Powerline主题 - 现代化设计（需要Nerd Font字体）

箭头无缝连接设计，需要Nerd Font支持，提供最佳视觉体验。

Capsule主题 - 胶囊样式（需要Nerd Font字体）

胶囊形状包装，现代化UI设计，适合追求简洁美观的用户。

强制启用特定模式

如果你的终端本就支持某种图标（例如Nerd Font），但没有自动启用，则可强制指定启用该图标能力

# 强制启用Nerd Font图标（需要安装字体，否则会显示乱码）
npx ccsp@latest --force-nerd-font

# 强制启用Emoji图标（需要终端确实支持Emoji，如MacOS，否则会显示乱码）
npx ccsp@latest --force-emoji  

# 强制启用纯文本模式
npx ccsp@latest --force-text

📊 Token计算准确性

与Claude官方API完全一致

状态栏的token计算与Claude官方API保持完全一致，确保显示数据的准确性：

如图所示：

• 状态栏显示：183.3k/200k (91.7%)
• Claude API报错：183559 + 21333 > 200000
• 计算结果：183559 ≈ 183.3k ✅ 完全一致

Token计算公式

contextUsedTokens = usage.input_tokens + 
                   usage.cache_creation_input_tokens + 
                   usage.cache_read_input_tokens + 
                   usage.output_tokens;

这确保了状态栏显示的token使用量与Claude官方统计完全一致。

💰 Cost计算说明

智能成本追踪系统

状态栏提供两种成本计算模式，可在 config.toml 中配置：

🔄 Session 模式（会话模式）

• 计算范围: 从您打开 Claude Code 开始，到使用 /clear 命令或关闭应用为止
• 计算逻辑: 基于当前会话的所有 token 消耗
• 适用场景: 单次工作会话的成本控制
• 重置方式: 使用 /clear 命令或重启 Claude Code

🔗 Conversation 模式（对话模式）

• 计算范围: 追踪完整对话链的累计消耗
• 智能追踪: 即使关闭并重新打开 Claude Code，仍能追踪同一项目的历史消耗
• Session 无关: 自动在本地缓存以记录每次中断/恢复/压缩的 token 变化，保持连续性追踪
• 适用场景: 长对话（可能含多次压缩）的完整成本分析

⚙️ 配置方式

在 config.toml 中设置：

[components.usage]
mode = "conversation"  # 或 "session"

💱 货币显示

usage 组件默认使用 currency = "auto"。自动模式会先应用你配置的 endpoint/model 规则，再匹配 model_providers，随后读取 Claude Code 传入的 cost.currency，最后回退到内置规则或 USD。DeepSeek、MiniMax、Kimi、GLM、百炼、火山方舟、MiMo 等 provider 已有默认 profile；其中中国站/国际站会分开匹配币种和价格。用户可以在 model_providers 中集中覆盖 endpoint、模型窗口、币种和价格。

注意：conversation 模式读取的是历史聚合的 total_cost_usd 存储值。为避免只换符号、不换金额，currency = "auto" 在该模式下会显示 USD；如果你确认自己的聚合成本已经是其他币种，可用 currency = "CNY" 等固定值强制显示。

[components.usage]
currency = "auto" # auto | USD | CNY | EUR | GBP | JPY ...

[model_providers.deepseek]
endpoints = ["api.deepseek.com"]
models = ["deepseek-*", "deepseek-chat", "deepseek-reasoner"]
currency = "CNY"

[model_providers.deepseek.context_windows]
"deepseek-chat" = 1_000_000
"deepseek-r1*" = 65_536

[model_providers.deepseek.pricing.deepseek-chat]
unit_tokens = 1_000_000
input = 1.0
output = 2.0
cache_read = 0.02

[components.usage.currency_endpoint_rules]
"api.example.cn" = "CNY"
"api.example.com" = "USD"

[components.usage.currency_model_rules]
"my-cny-model" = "CNY"

📊 成本计算方式

默认情况下，状态栏直接显示 Claude Code 传入的 cost.total_cost_usd。如果命中 model_providers.<name>.pricing，并且输入里包含 input/output/cache token 明细，则会按该 profile 的价格本地重算；缺少 token 明细时自动回退到上游金额。若 endpoint 已匹配到某个 provider，只会使用该 endpoint 所属 provider 的价格，避免中国站套用国际站价格。

注意: 状态栏的成本计算与 /cost 命令采用不同逻辑和时间范围，确保各自场景的准确性。

🛠️ 高级配置

智能配置管理系统

📂 配置文件层级

状态栏采用两级配置系统，支持灵活的配置管理：

项目级配置 (优先级: 高)

• 路径: ~/.claude/projects/{project-hash}/statusline-pro/config.toml
• 适用: 特定项目的个性化配置
• 初始化: npx ccsp@latest config init
• 初始化并复制组件模板: npx ccsp@latest config init -w

用户级配置 (优先级: 低)

• 路径: ~/.claude/statusline-pro/config.toml
• 适用: 全局默认配置，适用于所有项目
• 初始化: npx ccsp@latest config init -g
• 初始化并复制组件模板: npx ccsp@latest config init -w -g

⚡ 智能终端检测和配置初始化

运行初始化命令时，系统会自动检测您的终端能力：

# 初始化项目级配置（推荐）
npx ccsp@latest config init

# 初始化项目级配置并复制组件模板
npx ccsp@latest config init -w

# 初始化全局配置
npx ccsp@latest config init -g

# 强制重新初始化（覆盖现有配置）
npx ccsp@latest config init --force

提示：-w 等同于 --with-components，会把组件多行模板一并复制到配置目录，方便直接在本地调整。

智能检测功能：

• 🎨 Nerd Font 检测: 自动识别终端是否支持 Nerd Font 图标
• 😊 Emoji 支持检测: 检测终端的 Emoji 渲染能力
• 🌈 颜色支持检测: 识别终端的颜色显示能力
• 🎯 主题自动选择: 根据终端能力自动选择最佳主题

📝 配置文件详解

系统初始化后会生成完整的 config.toml 配置文件：

# 默认预设和主题
preset = "PMBTURS"
theme = "powerline"

# 主题特性配置
[themes.powerline]
enable_gradient = true
ignore_separator = true
fine_progress = true

# 组件顺序配置
[components]
order = ["project", "model", "branch", "tokens", "usage", "rate_limit", "status"]

# Token组件详细配置
[components.tokens]
show_gradient = true         # 启用彩色渐变进度条
show_progress_bar = true     # 显示进度条
show_percentage = true       # 显示百分比
progress_width = 15          # 进度条宽度

# 模型上下文窗口覆盖（内置已包含常见国产/第三方模型）
# 精确 key 优先于通配前缀；命中模型专属窗口时会覆盖 Claude Code stdin 的通用 200K。
[components.tokens.context_windows]
"deepseek-v4-*" = 1_000_000
"qwen-long*" = 10_000_000
"my-provider/my-model" = 500_000

# Token阈值配置
[components.tokens.thresholds]
warning = 60    # 60%显示黄色警告
danger = 85     # 85%显示红色危险
backup = 85     # 后备区域开始
critical = 95   # 95%显示🔥临界

# 终端兼容配置
[terminal]
force_nerd_font = false     # 强制启用Nerd Font
force_emoji = false         # 强制启用Emoji  
force_text = false          # 强制文本模式

🖥️ 终端兼容性

智能检测并自动适配不同终端环境：

• Windows Terminal ✅ 完全支持所有特性
• VS Code Terminal ✅ 完全支持所有特性
• iTerm2 (macOS) ✅ 完全支持所有特性
• Git Bash ✅ 完全支持所有特性
• PowerShell ✅ 完全支持所有特性
• CMD ⚠️ 自动回退到安全文本模式

🔧 故障排除

版本兼容性问题

Q: 状态栏完全不显示或显示错误

# 错误示例：status line command failed: npx ccsp@latest
# 解决方案：升级Claude Code到最新版本
npm install -g @anthropic-ai/claude-code@latest

Q: 提示"command not found: npx"或Node.js相关错误

# 错误示例：/bin/sh: npx: command not found
# 解决方案：安装或更新Node.js环境
# 访问官网下载最新版本：https://nodejs.org/
# 或使用包管理器安装：

# macOS (使用Homebrew)
brew install node

# Ubuntu/Debian
sudo apt update && sudo apt install nodejs npm

# Windows
# 请访问 https://nodejs.org/ 下载安装包

Q: Claude Code版本过旧导致的兼容性问题

# 检查Claude Code版本
claude --version

# 如果版本低于1.0.71，请更新
npm install -g @anthropic-ai/claude-code@latest

# 更新后重启终端并重新打开Claude Code

Q: Linux 上提示 libssl.so.3 找不到

自 v3.0.2