ccpet

A virtual pet for your Claude Code status line. The pet's energy decays over time, increases when you consume tokens, and persists across sessions.

Features

🐾 Virtual Pet System
- Energy-based pet that responds to your Claude Code usage
- Time-based decay (~0.0231 per minute, ~3 days from 100 → 0)
- Feeding via token usage (1,000,000 tokens = +1 energy)
🎭 Animated Expressions based on energy levels
- HAPPY (≥80): (^_^) (^o^) (^_^) (^v^) - Your pet is thriving!
- HUNGRY (≥40): (o_o) (O_O) (o_o) (-_-) - Needs some attention
- SICK (≥10): (u_u) (T_T) (u_u) (>_<) - Time to feed your pet
- DEAD (<10): (x_x) (X_X) (x_x) (+_+) - Your pet needs urgent care!
📊 Rich Status Display
- Colorful energy bar with precise energy values
- Accumulated tokens and lifetime statistics
- Real-time session metrics (input/output/cached/total)
- Pet birth time tracking for lifecycle management
⚙️ Configurable & Persistent
- Customizable colors and decay rates
- State persists across Claude Code sessions

Installation & Setup

Quick Start

To use ccpet as your Claude Code status line, add this to your ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "npx ccpet@latest",
    "padding": 0
  }
}

Alternative: Global Installation

For better performance, you can install globally:

npm install -g ccpet

Then update your settings to use the global path.

CLI Commands

Basic Usage

ccpet                    # Show status line (for Claude Code)
ccpet --help             # Show help information
ccpet --version          # Show version number

Pet Management Commands

Check Command

ccpet check              # Manually check pet status (no token cost)
ccpet check --watch      # Continuous monitoring mode (60s interval)
ccpet check -w --interval 30  # Watch mode with 30s interval
ccpet check --help       # Show check command help

Use ccpet check to:

✅ Check pet status without consuming tokens
✅ See time since last feeding
✅ Monitor energy levels between sessions
✅ NEW: Continuous monitoring with real-time updates
✅ NEW: Clean countdown display
✅ NEW: Customizable refresh intervals (10-300 seconds)

Configuration Command

ccpet config list        # Show current configuration
ccpet config set <key> <value>  # Set configuration value
ccpet config reset       # Reset to default configuration
ccpet config path        # Show configuration file location

Reset Command

ccpet reset              # Trigger pet death and graveyard preservation
ccpet reset --help       # Show reset command help

Use ccpet reset to:

✅ Manually trigger the pet death and preservation process
✅ Save current pet to graveyard with complete history
✅ Create a new pet with random name and fresh start
✅ Test the graveyard functionality
✅ NEW: Automatic history preservation in ~/.claude-pet/graveyard/

Sync Command

ccpet sync               # Sync pet and token usage data to Supabase
ccpet sync --dry-run     # Preview sync without making changes
ccpet sync --verbose     # Show detailed sync progress
ccpet sync --start-date 2024-01-01  # Sync from specific date
ccpet sync --end-date 2024-12-31    # Sync until specific date
ccpet sync --help        # Show sync command help

Use ccpet sync to:

✅ Upload pet records and token usage to Supabase database
✅ Enable cross-device pet history synchronization
✅ Support incremental syncing for efficiency
✅ Smart date range detection from pet birth time
✅ Batch processing for large datasets
✅ NEW: Cloud backup for pet graveyard data

Setup: ccpet comes with Supabase pre-configured for instant sync - just install and start using!

Web Leaderboard: View the global pet leaderboard online at https://ccpet.surge.sh/ - see how your pet ranks against others worldwide!

Leaderboard Command

ccpet leaderboard        # Show today's token leaderboard
ccpet leaderboard --period 7d     # Show 7-day leaderboard
ccpet leaderboard --period 30d    # Show 30-day leaderboard
ccpet leaderboard --period all    # Show all-time leaderboard
ccpet leaderboard --sort cost     # Sort by cost instead of tokens
ccpet leaderboard --sort survival # Sort by survival time
ccpet leaderboard --limit 20      # Show top 20 entries
ccpet leaderboard --verbose       # Show detailed query info
ccpet leaderboard --help          # Show leaderboard command help

Use ccpet leaderboard to:

✅ Compare your pet's performance with historical data
✅ Track token consumption and costs across time periods
✅ Monitor pet survival statistics and achievements
✅ Beautiful CLI table with emoji and formatting
✅ Automatic fallback to offline mode when Supabase unavailable
✅ NEW: Real-time countdown timers for ranking resets

Leaderboard Features:

Time Periods: today, 7d (7 days), 30d (30 days), all (all-time)
Sorting Options: tokens (default), cost, survival
Display: Rank, Pet Name, Type, Tokens, Cost, Survival Days, Status
Offline Mode: Automatically uses local graveyard data when cloud unavailable
Web Interface: View online leaderboard at https://ccpet.surge.sh/

Configuration Options:

# Colors (format: #RRGGBB or #RRGGBB:bright or #RRGGBB:bright:bold)
ccpet config set colors.petExpression "#FF0000:bright:bold"
ccpet config set colors.petName "#FF69B4:bright"
ccpet config set colors.energyBar "#00FF00"
ccpet config set colors.energyValue "#00FFFF"
ccpet config set colors.lifetimeTokens "#FF00FF"

# Pet behavior
ccpet config set pet.animationEnabled true
ccpet config set pet.decayRate 0.0231

# Multi-line display (NEW!)
ccpet config set display.maxLines 3                    # Show up to 3 lines (1-3)
ccpet config set display.line1.enabled true            # Enable/disable custom line 1
ccpet config set display.line1.items "expression,energy-bar,energy-value" # What to show on line 1
ccpet config set display.line2.enabled true            # Enable/disable line 2
ccpet config set display.line2.items "input,output"    # What to show on line 2
ccpet config set display.line3.enabled true            # Enable/disable line 3
ccpet config set display.line3.items "total"           # What to show on line 3

Available Display Items:

Line 1 Only: expression, energy-bar, energy-value, accumulated-tokens, lifetime-tokens, pet-name
Lines 2-3 Only: input, output, cached, total, context-length, context-percentage, context-percentage-usable, cost

Note: Currently, pet-related elements can only be used on Line 1, and session/context elements can only be used on Lines 2-3.

Continuous Pet Monitoring

Monitor your pet in real-time with the new watch mode:

# Start continuous monitoring (default 60s interval)
ccpet check --watch

# Custom monitoring interval (10-300 seconds)
ccpet check --watch --interval 30

# Short form
ccpet check -w --interval 45

Features:

✅ Real-time pet status updates
✅ Clean 3-line display layout
✅ Countdown timer showing next update
✅ Graceful exit with Ctrl+C
✅ Error recovery with retry mechanisms
✅ Customizable refresh intervals (10-300 seconds)
✅ In-place updates without screen flicker

Example Output:

Fluffy 🐶(^_^) ●●●●●●●●●● 100.00 (838.9K) 💖25.84M
⏰ 距离上次喂食: 0分钟前
⏳ 下次更新: 10秒

Note: The display updates in-place every interval, replacing the previous content for a clean monitoring experience.

Status Display

Default 3-Line Display

Luna 🐶(^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

Note: Pet names are controlled by including pet-name in the display.line1.items configuration. Position the pet-name element wherever you want it to appear on the first line. Context metrics (Ctx(u)) display in light green. Cost metrics show the total USD cost of your current session.

Single Line (Minimal)

Configure with: ccpet config set display.maxLines 1

Luna 🐶(^o^) ●●●●●●●●●● 98.52 (45.2K) 💖5.2M

2-Line Display (Balanced)

Configure with: ccpet config set display.maxLines 2

Luna 🐶(^o^) ●●●●●●●●●● 98.52 (45.2K) 💖5.2M
Input: 2847 Output: 1256 Cached: 512 Total: 4615

Custom Display Examples

With Pet Name Hidden

ccpet config set display.line1.items "expression,energy-bar,energy-value,accumulated-tokens,lifetime-tokens"

🐶(^o^) ●●●●●●●●●● 98.52 (45.2K) 💖5.2M
Input: 2847 Output: 1256 Cached: 512 Total: 4615

Name After Expression

ccpet config set display.line1.items "expression,pet-name,energy-bar,energy-value,accumulated-tokens,lifetime-tokens"

🐶(^o^) Luna ●●●●●●●●●● 98.52 (45.2K) 💖5.2M

Custom Line Configuration

ccpet config set display.line1.items "pet-name,expression,energy-value"
ccpet config set display.line2.items "input,output"
ccpet config set display.line3.items "total,context-percentage-usable"

Luna 🐶(^o^) 98.52
Input: 2847 Output: 1256
Total: 4615 Ctx(u): 88.5%

Display Format:

Line 1 (Pet Elements Only

Ccpet

Install / Use

README