claude-pulse 是一个 Claude Code CLI 的实时使用量监控工具

claude-pulse 详细部署教程

1. 项目简介

claude-pulse 是一个 Claude Code CLI 的实时使用量监控工具，由开发者 NoobyGains 维护。它在终端窗口底部显示状态栏，直观展示当前会话使用量、剩余时间、每周用量、模型用量、上下文窗口状态等信息，支持多种主题和动画效果。无需 API 密钥，自动识别订阅套餐。

核心特性：

• 实时使用监控：显示会话限额、每周配额和计划层级，用彩色进度条直观展示
• 零 API 调用：直接从 Claude Code 的 stdin 读取速率限制（v2.1.80+），无需 OAuth，无速率限制
• 10 种主题：default、ocean、sunset、mono、neon、pride、frost、ember、candy、rainbow
• 5 种动画模式：off、rainbow、pulse、glow、shift，每种视觉效果不同
• 8 种进度条样式：classic、block、shade、pipe、dot、square、star、braille
• 行数变化统计：以绿色/红色显示本次会话添加和删除的行数（如 +42 -7）
• 累计成本显示：可选的组件，显示所有会话的总 API 等效成本（缓存 5 分钟刷新）
• 组件优先级：每个组件都有优先级编号，可通过 --priority model=5,cost=15 重新排序
• 专注计时器：内置专注计时器，--focus start 25 在状态栏显示倒计时
• 自动更新通知：当 claude-pulse 或 Claude Code 有新版本时通知

系统要求：

根据官方文档和社区信息，部署需要满足以下条件：

• Python 3.6+：运行状态栏脚本
• 活跃的 Claude Code 订阅：Pro、Max 5x 或 Max 20x
• 操作系统：Windows、Linux、macOS

说明：claude-pulse 利用用户已有的 Claude Code OAuth 凭证获取精确的使用数据，无需单独的 API 密钥。

2. 部署前准备

2.1 环境检查

在开始部署之前，请确保：

• Claude Code CLI 已安装并可正常使用
• Python 3.6 或更高版本已安装
• 拥有活跃的 Claude Code 订阅

验证环境：

python3 --version
claude --version

2.2 安装方式选择

claude-pulse 提供三种安装方式，根据使用场景选择：

安装方式	适用场景	优势
插件市场	推荐方式	一条命令完成安装和配置
一键安装脚本	快速部署	自动处理安装流程
手动安装	开发者	完全可控，便于调试

3. 方式一：插件市场安装（推荐）

这是官方推荐的安装方式，通过 Claude Code 的插件系统完成安装。

3.1 添加插件市场

在 Claude Code 中执行：

/plugin marketplace add NoobyGains/claude-pulse

3.2 安装插件

/plugin install claude-pulse

3.3 配置

安装完成后，运行以下命令进行交互式配置：

/pulse

配置完成后，重启 Claude Code 使设置生效。

4. 方式二：一键安装脚本

适合快速部署，自动处理安装流程。

4.1 macOS / Linux 安装

打开终端，执行以下命令：

curl -fsSL https://raw.githubusercontent.com/NoobyGains/claude-pulse/main/install.sh | bash

4.2 Windows 安装

打开 PowerShell，执行以下命令：

irm https://raw.githubusercontent.com/NoobyGains/claude-pulse/main/install.ps1 | iex

4.3 启用实时心跳（可选）

心跳功能显示工具调用计数和经过时间，每次工具调用时更新：

python3 ~/.claude-pulse/claude_status.py --install-hooks

安装完成后需要重启 Claude Code 使钩子生效。

5. 方式三：手动安装（开发者）

适合需要修改源码或深度定制的开发者。

5.1 克隆项目

git clone https://github.com/NoobyGains/claude-pulse.git ~/.claude-pulse

5.2 运行安装脚本

python3 ~/.claude-pulse/claude_status.py --install

5.3 验证安装

安装完成后，重启 Claude Code，你应该能在终端底部看到状态栏。

6. 配置说明

6.1 交互式配置

在 Claude Code 中运行 /pulse 启动交互式设置向导。

6.2 命令行配置

也可以直接通过命令行参数进行配置：

主题设置：

--theme ocean              # 可选：ocean, sunset, mono, neon, pride, frost, ember, candy, rainbow

动画设置：

--animate rainbow          # 可选：rainbow, pulse, glow, shift, off
--animation-speed fast     # 可选：slow, normal, fast

显示设置：

--bar-size large           # 可选：small, small-medium, medium, medium-large, large
--bar-style block          # 可选：classic, block, shade, pipe, dot, square, star, braille
--layout compact           # 可选：standard, compact, minimal, percent-first
--wrap auto                # off（默认，截断）或 auto（窄屏时在 | 处换行到 2 行）

货币设置：

--currency £               # 支持 $, £, €, ¥, C$, A$, ₹, kr 等 20+ 种货币

预算设置：

--budget 25                # 设置预算上限，或使用 --budget off 关闭

限额设置：

--limits                   # 显示当前值
--limits subagent_spawns=200,subagent_concurrent=...

6.3 双行布局配置

编辑 config.json 实现双行布局：

{
  "line2_widgets": ["model", "effort", "branch"],
  "line1_widgets": ["session", "weekly"]
}

• line2_widgets：将这些组件推到第二行
• line1_widgets：允许第一行显示的组件，其余流向第二行
• 如果两者都设置，line1_widgets 优先

6.4 推荐配置：解决界面挤压问题

根据社区反馈，claude-pulse 的界面可能挤压 Claude Code 的通知消息（如 MCP 失败提示）。官方提供了快速修复方案：

/pulse minimal

该预设会：

• 使用小进度条 + 紧凑标签（“S”/“W”代替“Session”/“Weekly”）
• 隐藏计划名称、模型名称和上下文进度条
• 将输出限制为终端宽度的 60%

恢复完整界面：

/pulse default preset

其他调整方式：

• 运行 /pulse update 清除更新通知
• 解决失败的 MCP 服务器，避免 Claude Code 显示错误文本
• 使用 /pulse max-width 50 微调宽度（范围 20-100）

7. 使用指南

7.1 基本使用

安装并重启 Claude Code 后，状态栏会自动显示在终端底部。你可以实时查看：

• 会话限额和每周配额
• 当前使用的模型
• 上下文窗口使用情况
• Git 分支名称
• 行数变化统计

7.2 专注计时器

启动专注计时器：

--focus start 25           # 启动 25 分钟倒计时

倒计时会显示在状态栏中。

7.3 组件优先级调整

重新排列组件顺序：

--priority model=5,cost=15

每个组件都有优先级编号，数字越小优先级越高。

8. 常见问题与解决方案

8.1 状态栏挤压其他消息

问题：claude-pulse 的状态栏挤压了 Claude Code 的通知消息（如 MCP 服务器失败提示）。

原因：这是 Claude Code UI 的限制——状态栏和通知共享同一水平空间，claude-pulse 无法控制 Claude Code 如何定位自己的 UI 元素。

解决方案：

1. 使用最小化预设：

   /pulse minimal

2. 清除更新通知：

   /pulse update

3. 解决失败的 MCP 服务器

4. 手动调整宽度：

   /pulse max-width 50

8.2 数据不更新

问题：状态栏显示的数据长时间未更新。

解决方案：

• 确保 Claude Code 版本为 v2.1.80 或更高（零 API 调用功能需要此版本）
• 检查 Claude Code 凭证是否有效
• 如果升级了订阅套餐，可能需要刷新凭证

8.3 安装后状态栏不显示

问题：安装完成后看不到状态栏。

解决方案：

• 重启 Claude Code
• 检查是否运行了 /pulse 配置命令
• 验证 Python 环境是否正常

9. 注意事项

根据项目文档和社区信息，使用时请注意：

• 许可证：项目采用 “Source Available” 许可证，允许免费使用和修改，但限制再分发
• 订阅要求：需要活跃的 Claude Code 订阅（Pro、Max 5x 或 Max 20x）
• 凭证有效性：确保 Claude Code 凭证有效并已刷新，尤其是在升级套餐后
• 更新提示：Claude Code 更新指示器仅作信息提示，用户需手动更新 Claude Code

10. 部署架构总结

部署方式	适用场景	安装命令	特点
插件市场	推荐方式	/plugin install claude-pulse	一键完成，自动配置
一键脚本	快速部署	`curl …	bash`
手动安装	开发者	git clone && python3 ... --install	完全可控，便于调试

claude-pulse 是一个轻量级的 Claude Code 状态栏监控工具，通过插件市场或一键脚本可以快速完成部署。部署完成后，状态栏会自动显示在终端底部，实时展示使用量、配额和模型信息。建议初次使用时运行 /pulse minimal 预设，以平衡信息展示和界面空间，避免挤压 Claude Code 的其他通知消息。