ccpet
Version:
A Claude Code status line script that displays a virtual pet
256 lines (200 loc) • 8.05 kB
Markdown
# ccpet
[](https://badge.fury.io/js/ccpet)
[](https://www.npmjs.com/package/ccpet)
[](https://github.com/terryso/ccpet/actions)
[](https://opensource.org/licenses/MIT)
[English](README.md)
一个 Claude Code 状态栏虚拟宠物。宠物的能量会随时间衰减、在你消耗 token 时增加，并在会话之间持久化保存。
## 功能特性
- **🐾 虚拟宠物系统**
- 基于能量的宠物，响应你的 Claude Code 使用情况
- 基于时间的衰减（约每分钟 0.0231，约 3 天从 100 → 0）
- 通过 token 使用进行喂养（1,000,000 tokens = +1 能量）
- **🎭 动画表情** 基于能量等级
- **开心 (≥80)**: `(^_^) (^o^) (^_^) (^v^)` - 你的宠物很健康！
- **饥饿 (≥40)**: `(o_o) (O_O) (o_o) (-_-)` - 需要一些关注
- **生病 (≥10)**: `(u_u) (T_T) (u_u) (>_<)` - 是时候喂养你的宠物了
- **死亡 (<10)**: `(x_x) (X_X) (x_x) (+_+)` - 你的宠物需要紧急护理！
- **📊 丰富状态显示**
- 彩色能量条和精确的能量值
- 累计 token 和终身统计数据
- 实时会话指标（输入/输出/缓存/总计）
- 宠物诞生时间追踪，支持生命周期管理
- **⚙️ 可配置且持久化**
- 自定义颜色和衰减率
- 状态在 Claude Code 会话之间持久保存
## 安装和配置
### 快速开始
要将 ccpet 用作你的 Claude Code 状态栏，请在你的 `~/.claude/settings.json` 中添加：
```json
{
"statusLine": {
"type": "command",
"command": "npx ccpet@latest",
"padding": 0
}
}
```
### 替代方案：全局安装
为了更好的性能，你可以全局安装：
```bash
npm install -g ccpet
```
然后更新设置以使用全局路径。
## CLI 命令
### 基本用法
```bash
ccpet # 显示状态栏（用于 Claude Code）
ccpet --help # 显示帮助信息
ccpet --version # 显示版本号
```
### 宠物管理命令
#### 检查命令
```bash
ccpet check # 手动检查宠物状态（不消耗 token）
ccpet check --watch # 持续监控模式（60秒间隔）
ccpet check -w --interval 30 # 监控模式，30秒间隔
ccpet check --help # 显示检查命令帮助
```
使用 `ccpet check` 来：
- ✅ 检查宠物状态而不消耗 token
- ✅ 查看距离上次喂食的时间
- ✅ 监控会话之间的能量等级
- ✅ **新功能:** 持续监控，实时更新状态
- ✅ **新功能:** 简洁的倒计时显示
- ✅ **新功能:** 可自定义刷新间隔（10-300秒）
#### 配置命令
```bash
ccpet config list # 显示当前配置
ccpet config set <key> <value> # 设置配置值
ccpet config reset # 重置为默认配置
ccpet config path # 显示配置文件位置
```
**配置选项：**
```bash
# 颜色（格式：#RRGGBB 或 #RRGGBB:bright 或 #RRGGBB:bright:bold）
ccpet config set colors.petExpression "#FF0000:bright:bold"
ccpet config set colors.energyBar "#00FF00"
ccpet config set colors.energyValue "#00FFFF"
ccpet config set colors.lifetimeTokens "#FF00FF"
# 宠物行为
ccpet config set pet.animationEnabled true
ccpet config set pet.decayRate 0.0231
# 多行显示（新功能！）
ccpet config set display.maxLines 3 # 显示最多3行 (1-3)
ccpet config set display.line2.enabled true # 启用/禁用第2行
ccpet config set display.line2.items "input,output" # 第2行显示内容
ccpet config set display.line3.enabled true # 启用/禁用第3行
ccpet config set display.line3.items "total" # 第3行显示内容
```
**可用的显示项目：** `input`, `output`, `cached`, `total`, `context-length`, `context-percentage`, `context-percentage-usable`, `cost`
### 持续宠物监控
**使用新的监控模式实时观察你的宠物：**
```bash
# 开始持续监控（默认60秒间隔）
ccpet check --watch
# 自定义监控间隔（10-300秒）
ccpet check --watch --interval 30
# 简短形式
ccpet check -w --interval 45
```
**功能特性：**
- ✅ 实时宠物状态更新
- ✅ 简洁的3行显示布局
- ✅ 倒计时器显示下次更新时间
- ✅ Ctrl+C 优雅退出
- ✅ 错误恢复和重试机制
- ✅ 可自定义刷新间隔（10-300秒）
- ✅ 原地更新，无屏幕闪烁
**示例输出：**
```text
🐶(^_^) ●●●●●●●●●● 100.00 (838.9K) 💖25.84M
⏰ 距离上次喂食: 0分钟前
⏳ 下次更新: 10秒
```
**注意：** 显示内容会在每个间隔原地更新，替换之前的内容，提供清晰的监控体验。
**使用场景：**
- 🎯 监控宠物能量衰减过程
- 🎯 观察喂食后的能量恢复
- 🎯 跟踪长时间会话中的状态变化
- 🎯 调试和测试宠物系统行为
## 状态显示
### 默认3行显示
```text
(^o^) ●●●●●●●●●● 98.52 (45.2K) 💖5.2M
Input: 2847 Output: 1256 Cached: 512 Total: 4615
Ctx: 2.4K Ctx: 12.0% Ctx(u): 88.5% Cost: $0.15
```
**注意**: 上下文指标 (Ctx(u)) 现在默认显示为浅绿色。成本指标显示当前会话的总USD费用。
### 单行显示（极简）
配置：`ccpet config set display.maxLines 1`
```text
(^o^) ●●●●●●●●●● 98.52 (45.2K) 💖5.2M
```
### 2行显示（极简）
配置：`ccpet config set display.maxLines 2`
```text
(^o^) ●●●●●●●●●● 98.52 (45.2K) 💖5.2M
Input: 2847 Output: 1256 Cached: 512 Total: 4615
```
### 自定义3行显示
配置：
```bash
ccpet config set display.line2.items "input,output"
ccpet config set display.line3.items "total,context-percentage-usable"
```
```text
(^o^) ●●●●●●●●●● 98.52 (45.2K) 💖5.2M
Input: 2847 Output: 1256
Total: 4615 Ctx(u): 88.5%
```
**显示格式：**
- **第1行**（固定）: `[表情] [能量条] [能量值] ([累计 token]) 💖[终身 token]`
- **第2行**（可配置）: 你选择的自定义项目
- **第3行**（可配置）: 你选择的自定义项目
## 宠物照顾指南
### 🌟 保持宠物健康
- **积极使用**: 定期使用 Claude Code 来喂养你的宠物
- **Token 转换**: 1,000,000 tokens = +1 能量点
- **自然衰减**: 约每分钟 0.0231 能量（约 3 天完全衰减）
### 😴 当宠物死亡时
如果你的宠物能量降到 0：
- 所有统计数据都会重置（终身 token、累计 token）
- 宠物重生时会获得新的诞生时间
- 你的宠物可以通过继续使用 Claude Code 复活
- 每个新 token 都有助于从头重建你的宠物
## 故障排除
### 状态栏不更新？
状态栏只在你使用 Claude Code 时更新。使用 `ccpet check` 进行手动更新。
### 宠物消失了？
1. 检查 Claude Code 设置：`cat ~/.claude/settings.json`
2. 验证 ccpet 安装：`ccpet --version`
3. 手动测试：`ccpet check`
## 技术细节
### 数据存储
宠物状态保存在 `~/.claude-pet/pet-state.json` 文件中，包含以下结构：
- `energy`: 当前能量等级 (0-100)
- `expression`: 当前面部表情
- `animalType`: 宠物种类 (cat, dog, rabbit, panda, fox)
- `birthTime`: 宠物诞生/重生时间 (ISO时间戳)
- `lastFeedTime`: 上次喂食时间戳
- `totalTokensConsumed`: 本生命周期消耗的总token数
- `totalLifetimeTokens`: 终身token消耗量
- `accumulatedTokens`: 等待转换为能量的token数
系统会自动为旧版本状态文件添加缺失字段（如 `birthTime`）以保持向后兼容性。
## 开发
### 测试
```bash
npm test # 运行所有测试
npm run test:coverage # 运行测试并生成覆盖率报告
```
### 构建
```bash
npm run build # 构建分发文件
npm run watch # 构建并监视更改
```
## 许可证
MIT License
---
**享受你的虚拟编程伙伴！🐾**
*记住：喂得好的宠物是快乐的宠物。保持编码来保持你的宠物健康！*