ccstatusline 状态栏

Claude Code CLI 高度可定制的状态栏格式化工具

🎯 工具介绍

ccstatusline 是一款高度可定制的 Claude Code CLI 状态栏格式化工具，支持 Powerline 样式、主题和实时指标展示。在终端中显示模型信息、Git 分支、Token 用量、会话费用等数据。

核心功能

实时指标 — 显示模型名称、Git 分支、Token 用量、会话时长、Block 计时器等
完全可定制 — 选择展示的元素，自定义每个组件的颜色
Powerline 支持 — 漂亮的箭头分隔符、端盖和自定义字体
多行配置 — 设置多条独立的状态栏
交互式 TUI — 内置 React/Ink 配置界面
全局选项 — 统一格式化设置（边距、分隔符、粗体、背景色）
跨平台 — 支持 Bun 和 Node.js
智能宽度检测 — 自动适应终端宽度
零配置 — 合理的默认值，开箱即用

📦 安装方法

快速启动（无需安装）

bash

# 使用 npm
npx ccstatusline@latest

# 使用 Bun（更快）
bunx ccstatusline@latest

Windows 平台

方法一：使用 Bun（推荐）

powershell

# 安装 Bun
irm bun.sh/install.ps1 | iex

# 运行 ccstatusline
bunx ccstatusline@latest

方法二：使用 Node.js

powershell

npx ccstatusline@latest
# 或
yarn dlx ccstatusline@latest
# 或
pnpm dlx ccstatusline@latest

macOS / Linux

bash

# 使用 npm
npx ccstatusline@latest

# 使用 Bun（推荐，启动更快）
bunx ccstatusline@latest

WSL 环境

bash

curl -fsSL https://bun.sh/install | bash
source ~/.bashrc
bunx ccstatusline@latest

⚙️ 配置步骤

第一步：运行配置 TUI

执行安装命令后会自动打开交互式配置界面，支持：

配置多条独立状态栏
添加/删除/重排组件
自定义每个组件的颜色
配置弹性分隔符行为
编辑自定义文本组件
一键安装/卸载到 Claude Code 设置
实时预览状态栏效果

提示

设置会自动保存到 ~/.config/ccstatusline/settings.json

第二步：集成到 Claude Code

配置完成后，在 ~/.claude/settings.json 中添加：

Bun 用户：

json

{
  "statusLine": "bunx ccstatusline@latest"
}

npm 用户：

json

{
  "statusLine": "npx ccstatusline@latest"
}

自定义配置目录

如果 Claude Code 配置在非标准位置，设置 CLAUDE_CONFIG_DIR 环境变量：

bash

# Linux/macOS
export CLAUDE_CONFIG_DIR=/custom/path/to/.claude

# Windows PowerShell
$env:CLAUDE_CONFIG_DIR="C:\custom\path\.claude"

第三步：重启 Claude Code

配置完成后重启 Claude Code 即可在终端底部看到状态栏。

📊 可用组件

核心组件

组件	说明
Model Name	当前 Claude 模型名称
Git Branch	当前 Git 分支
Git Changes	未提交的增删行数（如 "+42,-10"）
Git Worktree	当前 Git Worktree 名称
Session Clock	会话已用时间（如 "2hr 15m"）
Session Cost	会话总费用（如 "$1.23"）
Session Name	通过 `/rename` 设置的会话名
Block Timer	5 小时 Block 进度计时
CWD	当前工作目录（可配置段数）
Version	Claude Code 版本号
Output Style	当前输出样式

Token 组件

组件	说明
Tokens Input	输入 Token 数
Tokens Output	输出 Token 数
Tokens Cached	缓存 Token 数
Tokens Total	总 Token 数
Context Length	当前上下文长度
Context Percentage	上下文使用百分比（支持剩余模式切换）
Context Percentage (usable)	可用上下文百分比（考虑 80% auto-compact）

系统组件

组件	说明
Terminal Width	终端宽度
Memory Usage	系统内存使用量（如 "Mem: 12.4G/16.0G"）
Custom Text	自定义静态文本
Custom Command	执行 Shell 命令并展示输出
Separator	可视化分隔符（可定制样式）
Flex Separator	自动扩展填充可用空间

⏱️ Block Timer 组件

追踪 Claude Code 5 小时对话 Block 的进度：

显示模式：

时间显示 — 显示已用时间如 "3hr 45m"（默认）
进度条 — 32 字符宽进度条 + 百分比
紧凑进度条 — 16 字符宽进度条 + 百分比

自动从会话时间戳检测 Block 边界，支持在 TUI 中按 (p) 键切换模式。

🔧 自定义组件

Custom Text

在状态栏中添加静态文本，适用于：

项目标识
环境指示（dev/prod）
个人标签

Custom Command

执行 Shell 命令并动态展示输出：

bash

# 示例命令
pwd | xargs basename         # 当前目录名
node -v                      # Node.js 版本
git rev-parse --short HEAD   # 当前 commit hash
date +%H:%M                  # 当前时间

注意

命令应快速完成，长时间运行的命令会在超时后被终止。如果看不到输出，尝试增加超时时间（在编辑器中按 t 键）。

🎨 Powerline 模式

v2.0.0 引入了 Powerline 支持：

箭头样式分隔符和可定制端盖
多种内置主题可复制和自定义
支持 16 色、256 色和 Truecolor（Hex）模式
组件合并功能实现无缝设计
多行自动对齐

Windows 字体配置

Powerline 模式需要 Nerd Font 支持：

powershell

# 安装 JetBrains Mono Nerd Font
winget install DEVCOM.JetBrainsMonoNerdFont

Windows Terminal 推荐配置：

json

{
  "profiles": {
    "defaults": {
      "font": {
        "face": "JetBrainsMono Nerd Font",
        "size": 12
      },
      "colorScheme": "One Half Dark"
    }
  }
}

⚙️ 全局选项

配置全局格式化偏好，应用于所有组件：

默认边距 — 为每个组件添加统一的左右边距
默认分隔符 — 自动在组件间插入分隔符
继承颜色 — 分隔符继承前一个组件的颜色
全局粗体 — 为所有文本应用粗体格式
覆盖前景色/背景色 — 强制所有组件使用相同颜色

终端宽度选项

选项	说明
Full width always	始终使用完整终端宽度
Full width minus 40	预留 40 字符给 auto-compact 消息（默认）
Full width until compact	根据上下文百分比阈值动态切换

VSCode 用户

如果 VSCode 集成终端中颜色显示不正确，将 terminal.integrated.minimumContrastRatio 设置为 1 可禁用对比度强制调整。

🔍 故障排查

Powerline 符号显示为方块

powershell

# 安装兼容的 Nerd Font
winget install JetBrainsMono.NerdFont
# 然后在终端设置中指定该字体

Git 命令无法识别

powershell

git --version
# 如未找到，安装 Git：
winget install Git.Git

权限错误

powershell

# 使用非全局安装（推荐）
npx ccstatusline@latest

PowerShell 执行策略错误

powershell

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Windows Defender 拦截

在 Windows 安全中心将 ccstatusline 二进制文件路径添加到排除列表。

🔗 项目资源

GitHub 仓库：https://github.com/sirmalloc/ccstatusline
npm 包：ccstatusline
问题反馈：GitHub Issues
许可证：MIT

🙏 致谢

感谢 Matthew Breedlove (@sirmalloc) 开发此工具，为 Claude Code 社区提供了强大的状态栏解决方案。

ccstatusline 状态栏 ​

🎯 工具介绍 ​

核心功能 ​

📦 安装方法 ​

快速启动（无需安装） ​

Windows 平台 ​

macOS / Linux ​

WSL 环境 ​

⚙️ 配置步骤 ​

第一步：运行配置 TUI ​

第二步：集成到 Claude Code ​

第三步：重启 Claude Code ​

📊 可用组件 ​

核心组件 ​

Token 组件 ​

系统组件 ​

⏱️ Block Timer 组件 ​

🔧 自定义组件 ​

Custom Text ​

Custom Command ​

🎨 Powerline 模式 ​

Windows 字体配置 ​

⚙️ 全局选项 ​

终端宽度选项 ​

🔍 故障排查 ​

Powerline 符号显示为方块 ​

Git 命令无法识别 ​

权限错误 ​

PowerShell 执行策略错误 ​

Windows Defender 拦截 ​

🔗 项目资源 ​

🙏 致谢 ​

ccstatusline 状态栏

🎯 工具介绍

核心功能

📦 安装方法

快速启动（无需安装）

Windows 平台

macOS / Linux

WSL 环境

⚙️ 配置步骤

第一步：运行配置 TUI

第二步：集成到 Claude Code

第三步：重启 Claude Code

📊 可用组件

核心组件

Token 组件

系统组件

⏱️ Block Timer 组件

🔧 自定义组件

Custom Text

Custom Command

🎨 Powerline 模式

Windows 字体配置

⚙️ 全局选项

终端宽度选项

🔍 故障排查

Powerline 符号显示为方块

Git 命令无法识别

权限错误

PowerShell 执行策略错误

Windows Defender 拦截

🔗 项目资源

🙏 致谢