ccsp

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

##### 😊 Emoji 模式

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

##### 📝 文本模式

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

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

!Powerline效果

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

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

!Capsule效果

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

#### 强制启用特定模式

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

`bash

`强制启用Nerd Font图标（需要安装字体，否则会显示乱码）`


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

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

npx ccsp@latest --force-text


$3
#### 与Claude官方API完全一致
状态栏的token计算与Claude官方API保持完全一致，确保显示数据的准确性：
!Token计算准确性对比
如图所示：

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

#### Token计算公式

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

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

`$3`

#### 智能成本追踪系统

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

##### 🔄 Session 模式（会话模式）

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

##### 🔗 Conversation 模式（对话模式）

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

##### ⚙️ 配置方式

在 config.toml 中设置：

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

##### 📊 成本计算公式

`javascript cost = (inputTokens inputPrice + outputTokens outputPrice + cacheTokens * cachePrice) / 200_000`

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

`$3`

#### 智能配置管理系统

##### 📂 配置文件层级

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

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

- 路径: ~/.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

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

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

`bash

`初始化项目级配置（推荐）`


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 配置文件：

`toml

`默认预设和主题`


preset = "PMBTUS"
theme = "powerline"
主题特性配置

[themes.powerline]
enable_gradient = true
ignore_separator = true
fine_progress = true
组件顺序配置

[components]
order = ["project", "model", "branch", "tokens", "usage", "status"]
Token组件详细配置

[components.tokens]
show_gradient = true         # 启用彩色渐变进度条
show_progress_bar = true     # 显示进度条
show_percentage = true       # 显示百分比
progress_width = 15          # 进度条宽度
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          # 强制文本模式


$3
智能检测并自动适配不同终端环境：
- Windows Terminal ✅ 完全支持所有特性
- VS Code Terminal ✅ 完全支持所有特性
- iTerm2 (macOS) ✅ 完全支持所有特性
- Git Bash ✅ 完全支持所有特性
- PowerShell ✅ 完全支持所有特性
- CMD ⚠️ 自动回退到安全文本模式
$3
#### 版本兼容性问题
##### Q: 状态栏完全不显示或显示错误

`bash

`错误示例：status line command failed: npx ccsp@latest`


解决方案：升级Claude Code到最新版本

npm install -g @anthropic-ai/claude-code@latest


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

`bash

`错误示例：/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版本过旧导致的兼容性问题

`bash

`检查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 起，Linux x64/ARM64 平台包改为 musl 静态链接构建，不再依赖系统自带的 OpenSSL；请执行以下步骤：

1. 确认使用最新版本：npx ccsp@latest --version2. 若仍提示旧二进制，可清理 npm 缓存后重试：`bash npm cache clean --force npx ccsp@latest --version`3. 仍需手动安装依赖的老版本用户，可按发行说明安装libssl3 或升级系统，但建议尽快迁移到 3.0.2+。

#### 显示问题

##### Q: 图标显示为方框或乱码

`bash

`检查终端是否支持Nerd Font，强制使用Emoji模式`


npx ccsp@latest --force-emoji


##### Q: 颜色显示异常

`bash

`检查终端颜色支持，可以禁用颜色`


npx ccsp@latest --no-color


##### Q: 状态栏不更新

`bash

`检查Claude Code配置文件是否正确`


cat ~/.claude/settings.json


#### 测试命令

`bash

`测试基本功能`


echo '{"model":{"id":"claude-sonnet-4"}}' | npx ccsp@latest
测试特定预设和主题

echo '{"model":{"id":"claude-sonnet-4"}}' | npx ccsp@latest --preset MT --theme classic


---
User Guide
Claude Code Professional Status Bar - Smart status bar system specifically designed for Claude Code.
$3

- 🎯 Three Theme System: Classic, Powerline, and Capsule themes with adaptive terminal capabilities - 🛠️ Flexible Configuration System: Support for TOML configuration files and command-line parameter overrides - 📊 Precise Token Calculation: Token statistics fully consistent with Claude's official API, supporting gradient visualization progress bar - 🧠 Smart Status Recognition: Precise identification of Thinking vs Ready status based on token count - 🚀 Preset System: Quick component configuration through letter combinations (PMBTUS, MT, BT) - 🌈 Cross-platform Compatibility: Smart adaptation for Windows, macOS, Linux, supporting various terminals - 🧩 Multiline Widget System: Grid-based widgets with static/API sources, auto-detection, and JSONPath filters - ⚡ High Performance Optimization: Caching mechanism, 300ms update interval, following Claude Code official recommendations - 🌐 Bilingual Support: Chinese and English configuration interface with error messages - 🦀 Rust Engine: Native Rust core for faster, more stable statusline updates

`$3`

- Native git2repository analysis: reads branch status, stash counts, and operations without spawning shells, keeping large repos responsive - Layered caching system: in-memory component caches plus persisted session storage to avoid redundant config/history IO - Tokio-powered async runtime: multi-threaded scheduling separates rendering from file work, maintaining the 300ms refresh cadence with higher stability - Incremental transcript parsing: seeks to the last processed offset and persists snapshots atomically so large.jsonllogs no longer stall refreshes - Cached config and widgets: merged configurations are reused with diff reports, while multiline widgets memoize their last render to smooth IO and API calls

`$3`

Before getting started, please ensure your system meets the following requirements:

#### Prerequisites

- Claude Code: Version ≥ 1.0.71 - Node.js: Version ≥ 18.0.0 (Download) - npm: Usually installed automatically with Node.js

#### Check Current Versions

`bash

`Check Claude Code version`


claude --version
Check Node.js version

node --version
Check npm version

npm --version


$3
#### One-Step Configuration, Instant Use
Simply add one line to your Claude Code configuration file, no pre-installation required:

Create .claude/settings.json in your project root or home directory:

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

> 💡 Compatibility Note: The legacy command npx ccsp@latest still works and forwards to the new package, but will emit a migration warning. Updating existing configs to npx ccsp@latest keeps future upgrades smooth.

Save the file and restart Claude Code to see the professional status bar!

#### Verify Installation

Open Claude Code and you should see a status bar like this:

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

`$3`

#### Preset System - Letter Combination Configuration

Quickly customize status bar content through simple letter combinations:

- P = Project (project name) - M = Model (model information) - B = Branch (Git branch) - T = Tokens (token usage) - U = Usage (usage statistics) - S = Status (status information)

#### Quick Configuration Commands

Note: These commands are all written in settings.json, not executed directly in the terminal (direct execution will print preview results)

`bash

`Show all components (recommended)`


npx ccsp@latest --preset PMBTUS --theme powerline
Show only model, tokens, and usage

npx ccsp@latest --preset MTU --theme classic
Show only branch and token information

npx ccsp@latest --preset BT --theme capsule


$3
The multiline engine turns the status bar into a grid of independently refreshing widgets.

- Grid layout: Use row (1-based) and col(0-based) to place each widget and build multi-row layouts. - Widget types: Built-instatic (text) and api(HTTP request) widgets with template rendering and environment variable substitution. - Auto detection:detection blocks read environment variables and support equals / contains / pattern, with optional forceoverrides. - Result filters:filter combines JSONPath with equals / contains / patternso widgets refresh only when keywords match—perfect for last-request panels. - Starter templates: Copyconfigs/components/usage.template.toml or rust/configs/components/usage.template.toml to ~/.claude/statusline-pro/components/usage.toml and customize.

#### Quick Enable

Enable multiline mode in config.toml and point to your widget file:

`toml [multiline] enabled = true`

Run npx ccsp@latest config init -w to generate the main config and copy all widget templates in one step.

`$3`

#### Classic Theme - Maximum Compatibility

Classic theme supports three icon modes, automatically selected based on terminal capabilities by default:

##### 🎯 Nerd Font Mode (Recommended)

Requires Nerd Font installation and selecting the font in the corresponding terminal, recommend Hack Nerd Font

##### 😊 Emoji Mode

Suitable for terminals that support Emoji but don't have Nerd Font

##### 📝 Text Mode

Maximum compatibility, suitable for all terminal environments

#### Powerline Theme - Modern Design (Requires Nerd Font)

!Powerline Effect

Seamless arrow connection design, requires Nerd Font support, provides the best visual experience.

#### Capsule Theme - Capsule Style (Requires Nerd Font)

!Capsule Effect

Capsule-shaped wrapper, modern UI design, suitable for users pursuing simplicity and beauty.

#### Force Enable Specific Mode

If your terminal already supports certain icons (e.g., Nerd Font) but doesn't auto-enable, you can force enable that icon capability

`bash

`Force enable Nerd Font icons (requires font installation, otherwise will show garbled text)`


npx ccsp@latest --force-nerd-font
Force enable Emoji icons (terminal must actually support Emoji like macOS, otherwise will show garbled text)

npx ccsp@latest --force-emoji  
Force enable plain text mode

npx ccsp@latest --force-text


$3
#### Fully Consistent with Claude Official API
The status bar's token calculation remains fully consistent with Claude's official API, ensuring accurate data display:
!Token Calculation Accuracy Comparison
As shown in the image:

- Status bar display: 183.3k/200k (91.7%)- Claude API error:183559 + 21333 > 200000- Calculation result:183559 ≈ 183.3k ✅ Completely consistent

#### Token Calculation Formula

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

This ensures that the token usage displayed in the status bar is completely consistent with Claude's official statistics.

`$3`

#### Intelligent Cost Tracking System

The status bar provides two cost calculation modes, configurable in config.toml:

##### 🔄 Session Mode

- Calculation scope: From when you open Claude Code until using /clearcommand or closing the application - Calculation logic: Based on all token consumption in the current session - Use case: Cost control for single work sessions - Reset method: Use/clear command or restart Claude Code

##### 🔗 Conversation Mode

- Scope: Tracks cumulative usage across the entire conversation chain - Smart Tracking: Continues following the same project’s history even after closing and reopening Claude Code - Session-Agnostic: Persists local snapshots of token changes for every pause/resume/compression to maintain continuity - Best For: Long-running conversations (often with multiple compressions) that need full cost analysis

##### ⚙️ Configuration Method

Set in config.toml:

`toml [components.usage] mode = "conversation" # or "session"`

##### 📊 Cost Calculation Formula

`javascript cost = (inputTokens inputPrice + outputTokens outputPrice + cacheTokens * cachePrice) / 200_000`

Note: The status bar's cost calculation uses different logic and time ranges from the /cost command, ensuring accuracy for their respective scenarios.

`$3`

#### Intelligent Configuration Management System

##### 📂 Configuration File Hierarchy

The status bar uses a two-level configuration system for flexible configuration management:

Project-level Configuration (Priority: High)

- Path: ~/.claude/projects/{project-hash}/statusline-pro/config.toml- Application: Personalized configuration for specific projects - Initialization:npx ccsp@latest config init- Initialization with component templates:npx ccsp@latest config init -w

User-level Configuration (Priority: Low)

- Path: ~/.claude/statusline-pro/config.toml- Application: Global default configuration for all projects - Initialization:npx ccsp@latest config init -g- Initialization with component templates:npx ccsp@latest config init -w -g

#### ⚡ Smart Terminal Detection and Configuration Initialization

When running initialization commands, the system automatically detects your terminal capabilities:

`bash

`Initialize project-level configuration (recommended)`


npx ccsp@latest config init
Initialize project-level configuration and copy component templates

npx ccsp@latest config init -w
Initialize global configuration

npx ccsp@latest config init -g
Force re-initialization (overwrite existing configuration)

npx ccsp@latest config init --force

> Tip: -w is the short form of --with-components; it copies the bundled multiline widget templates into your config folder so you can customize them locally.

Smart Detection Features:

- 🎨 Nerd Font Detection: Automatically identifies if terminal supports Nerd Font icons - 😊 Emoji Support Detection: Detects terminal's emoji rendering capability - 🌈 Color Support Detection: Identifies terminal's color display capability - 🎯 Automatic Theme Selection: Automatically selects the best theme based on terminal capabilities

#### 📝 Configuration File Details

After system initialization, a complete config.toml configuration file will be generated:

`toml

`Default preset and theme`


preset = "PMBTUS"
theme = "powerline"
Theme feature configuration

[themes.powerline]
enable_gradient = true
ignore_separator = true
fine_progress = true
Component order configuration

[components]
order = ["project", "model", "branch", "tokens", "usage", "status"]
Token component detailed configuration

[components.tokens]
show_gradient = true         # Enable colored gradient progress bar
show_progress_bar = true     # Show progress bar
show_percentage = true       # Show percentage
progress_width = 15          # Progress bar width
Token threshold configuration

[components.tokens.thresholds]
warning = 60    # 60% shows yellow warning
danger = 85     # 85% shows red danger
backup = 85     # Backup area starts
critical = 95   # 95% shows 🔥 critical
Terminal compatibility configuration

[terminal]
force_nerd_font = false     # Force enable Nerd Font
force_emoji = false         # Force enable Emoji
force_text = false          # Force text mode


$3
Smart detection and automatic adaptation for different terminal environments:
- Windows Terminal ✅ Full support for all features
- VS Code Terminal ✅ Full support for all features
- iTerm2 (macOS) ✅ Full support for all features
- Git Bash ✅ Full support for all features
- PowerShell ✅ Full support for all features
- CMD ⚠️ Automatic fallback to safe text mode
$3
$3
#### Q: Status bar not displaying or showing errors

`bash

`Error example: status line command failed: npx ccsp@latest`


Solution: Upgrade Claude Code to the latest version

npm install -g @anthropic-ai/claude-code@latest


#### Q: "command not found: npx" or Node.js related errors

`bash

`Error example: /bin/sh: npx: command not found`


Solution: Install or update Node.js environment

Visit official website for latest version: https://nodejs.org/

Or use package managers:
macOS (using Homebrew)

brew install node
Ubuntu/Debian

sudo apt update && sudo apt install nodejs npm
Windows

Please visit https://nodejs.org/ to download installer


#### Q: Compatibility issues due to outdated Claude Code version

`bash

`Check Claude Code version`


claude --version
If version is below 1.0.71, please update

npm install -g @anthropic-ai/claude-code@latest
Restart terminal and reopen Claude Code after update


$3
#### Q: Icons display as squares or garbled text

`bash

`Check if terminal supports Nerd Font, force use Emoji mode`


npx ccsp@latest --force-emoji


#### Q: Color display issues

`bash

`Check terminal color support, can disable colors`


npx ccsp@latest --no-color


#### Q: Status bar not updating

`bash

`Check if Claude Code configuration file is correct`


cat ~/.claude/settings.json

$3

`bash

`Test basic functionality`


echo '{"model":{"id":"claude-sonnet-4"}}' | npx ccsp@latest
Test specific preset and theme

echo '{"model":{"id":"claude-sonnet-4"}}' | npx ccsp@latest --preset MT --theme classic

Claude Code Statusline Pro

![npm version](https://badge.fury.io/js/ccsp)
![License: MIT](https://opensource.org/licenses/MIT)
![Node.js](https://nodejs.org/)
![Platform](https://github.com/wangnov/ccsp)

中文 | English

---

使用指南

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

$3

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

#### 必需条件

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

#### 检查当前版本

``bash

`检查Claude Code版本`


claude --version
检查Node.js版本

node --version
检查npm版本

npm --version


$3
#### 一步配置，即刻使用
只需要在Claude Code的配置文件中添加一行配置，无需预先安装：

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

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

> 💡 兼容说明：旧命令 npx ccsp@latest 仍会继续工作并自动调用新包，但将显示迁移提示。建议尽快将现有配置更新为 npx ccsp@latest 以保持一致。

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

#### 验证安装

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

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

`$3`

#### 预设系统 - 字母组合配置

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

- P = Project (项目名称) - M = Model (模型信息) - B = Branch (Git分支) - T = Tokens (Token使用情况) - U = Usage (使用量统计) - S = Status (状态信息)

#### 快速配置命令

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

`bash

`显示所有组件（推荐）`


npx ccsp@latest --preset PMBTUS --theme powerline
只显示模型、Token和使用量

npx ccsp@latest --preset MTU --theme classic
只显示分支和Token信息

npx ccsp@latest --preset BT --theme capsule


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

#### 快速启用

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

`toml [multiline] enabled = true`

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

`$3`

#### Classic 主题 - 最大兼容性

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

##### 🎯 Nerd Font 模式（推荐）

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

##### 😊 Emoji 模式

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

##### 📝 文本模式

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

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

!Powerline效果

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

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

!Capsule效果

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

#### 强制启用特定模式

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

`bash

`强制启用Nerd Font图标（需要安装字体，否则会显示乱码）`


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

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

npx ccsp@latest --force-text


$3
#### 与Claude官方API完全一致
状态栏的token计算与Claude官方API保持完全一致，确保显示数据的准确性：
!Token计算准确性对比
如图所示：

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

#### Token计算公式

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

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

`$3`

#### 智能成本追踪系统

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

##### 🔄 Session 模式（会话模式）

##### 🔗 Conversation 模式（对话模式）

##### ⚙️ 配置方式

在 config.toml 中设置：

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

##### 📊 成本计算公式

`javascript cost = (inputTokens inputPrice + outputTokens outputPrice + cacheTokens * cachePrice) / 200_000`

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

`$3`

#### 智能配置管理系统

##### 📂 配置文件层级

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

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

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

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

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

`bash

`初始化项目级配置（推荐）`


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，会把组件多行模板一并复制到配置目录，方便直接在本地调整。

智能检测功能：

##### 📝 配置文件详解

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

`toml

`默认预设和主题`


preset = "PMBTUS"
theme = "powerline"
主题特性配置

[themes.powerline]
enable_gradient = true
ignore_separator = true
fine_progress = true
组件顺序配置

[components]
order = ["project", "model", "branch", "tokens", "usage", "status"]
Token组件详细配置

[components.tokens]
show_gradient = true         # 启用彩色渐变进度条
show_progress_bar = true     # 显示进度条
show_percentage = true       # 显示百分比
progress_width = 15          # 进度条宽度
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          # 强制文本模式


$3
智能检测并自动适配不同终端环境：
- Windows Terminal ✅ 完全支持所有特性
- VS Code Terminal ✅ 完全支持所有特性
- iTerm2 (macOS) ✅ 完全支持所有特性
- Git Bash ✅ 完全支持所有特性
- PowerShell ✅ 完全支持所有特性
- CMD ⚠️ 自动回退到安全文本模式
$3
#### 版本兼容性问题
##### Q: 状态栏完全不显示或显示错误

`bash

`错误示例：status line command failed: npx ccsp@latest`


解决方案：升级Claude Code到最新版本

npm install -g @anthropic-ai/claude-code@latest


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

`bash

`错误示例：/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版本过旧导致的兼容性问题

`bash

`检查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 起，Linux x64/ARM64 平台包改为 musl 静态链接构建，不再依赖系统自带的 OpenSSL；请执行以下步骤：

#### 显示问题

##### Q: 图标显示为方框或乱码

`bash

`检查终端是否支持Nerd Font，强制使用Emoji模式`


npx ccsp@latest --force-emoji


##### Q: 颜色显示异常

`bash

`检查终端颜色支持，可以禁用颜色`


npx ccsp@latest --no-color


##### Q: 状态栏不更新

`bash

`检查Claude Code配置文件是否正确`


cat ~/.claude/settings.json


#### 测试命令

`bash

`测试基本功能`


echo '{"model":{"id":"claude-sonnet-4"}}' | npx ccsp@latest
测试特定预设和主题

echo '{"model":{"id":"claude-sonnet-4"}}' | npx ccsp@latest --preset MT --theme classic


---
User Guide
Claude Code Professional Status Bar - Smart status bar system specifically designed for Claude Code.
$3

`$3`

Before getting started, please ensure your system meets the following requirements:

#### Prerequisites

- Claude Code: Version ≥ 1.0.71 - Node.js: Version ≥ 18.0.0 (Download) - npm: Usually installed automatically with Node.js

#### Check Current Versions

`bash

`Check Claude Code version`


claude --version
Check Node.js version

node --version
Check npm version

npm --version


$3
#### One-Step Configuration, Instant Use
Simply add one line to your Claude Code configuration file, no pre-installation required:

Create .claude/settings.json in your project root or home directory:

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

Save the file and restart Claude Code to see the professional status bar!

#### Verify Installation

Open Claude Code and you should see a status bar like this:

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

`$3`

#### Preset System - Letter Combination Configuration

Quickly customize status bar content through simple letter combinations:

- P = Project (project name) - M = Model (model information) - B = Branch (Git branch) - T = Tokens (token usage) - U = Usage (usage statistics) - S = Status (status information)

#### Quick Configuration Commands

Note: These commands are all written in settings.json, not executed directly in the terminal (direct execution will print preview results)

`bash

`Show all components (recommended)`


npx ccsp@latest --preset PMBTUS --theme powerline
Show only model, tokens, and usage

npx ccsp@latest --preset MTU --theme classic
Show only branch and token information

npx ccsp@latest --preset BT --theme capsule


$3
The multiline engine turns the status bar into a grid of independently refreshing widgets.

#### Quick Enable

Enable multiline mode in config.toml and point to your widget file:

`toml [multiline] enabled = true`

Run npx ccsp@latest config init -w to generate the main config and copy all widget templates in one step.

`$3`

#### Classic Theme - Maximum Compatibility

Classic theme supports three icon modes, automatically selected based on terminal capabilities by default:

##### 🎯 Nerd Font Mode (Recommended)

Requires Nerd Font installation and selecting the font in the corresponding terminal, recommend Hack Nerd Font

##### 😊 Emoji Mode

Suitable for terminals that support Emoji but don't have Nerd Font

##### 📝 Text Mode